Eine Docusaurus-ähnliche Website mit FastAPI erstellen: Schritt 3 – Codehervorhebung

In vorherigen Artikel haben wir Unterstützung für die dynamische Anzeige von HTML aus .md-Dateien hinzugefügt.

Aber wie Sie gesehen haben, wurde der Python-Codeblock in docs/hello.md gerendert, er sah aber schlicht aus und hatte keine Farb-Hervorhebung, was das Lesen erschwerte.

In diesem Artikel werden wir dieses Problem lösen: mit Pygments und python-markdown-Erweiterungen, um unseren Markdown-Codeblöcken Syntaxhervorhebung hinzuzufügen.

Schritt 1: Abhängigkeiten für die Hervorhebung installieren

Die Bibliothek python-markdown unterstützt zusätzliche Funktionen über "Erweiterungen". Um die Codehervorhebung zu implementieren, benötigen wir die Erweiterung codehilite, die wiederum von einer anderen Bibliothek abhängt: Pygments.

Führen Sie den folgenden Befehl aus, um Pygments zu installieren:

pip install Pygments

Schritt 2: Verzeichnis für statische Dateien und CSS konfigurieren

Die Syntaxhervorhebung funktioniert in zwei Schritten:

Die codehilite-Erweiterung von python-markdown wandelt Codeblöcke (z.B. ```python ... ```) in HTML-Tags mit spezifischen CSS-Klassen (wie .k für Keyword, .s für String) um.
Verwenden Sie eine CSS-Datei, um dem Browser mitzuteilen, welche Farben diese CSS-Klassen anzeigen sollen.

Die Bibliothek Pygments stellt ein praktisches Kommandozeilenwerkzeug zur Generierung dieses CSS bereit.

Erstellen wir zunächst einen Ordner static/css im Stammverzeichnis unseres Projekts, um diese CSS-Datei zu speichern.

fastapi-docs-site/
├── docs/
│   └── hello.md
├── main.py
├── static/
│   └── css/          <-- Neu
└── templates/

Schritt 3: Die CSS-Datei für die Hervorhebung generieren

Öffnen Sie Ihr Terminal und führen Sie den folgenden Befehl aus:

pygmentize -S monokai -f html -a .codehilite > static/css/highlight.css

Hier ist eine Erklärung der pygmentize-Parameter:

-S monokai: Gibt monokai als Hervorhebungsthema an (Sie können auch default, github-dark, solarized-light usw. ausprobieren).
-f html: -f gibt an, dass wir CSS für HTML generieren möchten.
-a .codehilite: -a bedeutet, dass alle CSS-Regeln unter der CSS-Klasse .codehilite verschachtelt werden sollen (dies ist die Standardklasse, die von python-markdown verwendet wird).

Nachdem es abgeschlossen ist, öffnen Sie static/css/highlight.css, und Sie sehen die generierten CSS-Regeln für das monokai-Thema.

Schritt 4: Das statische Verzeichnis in FastAPI einbinden

Jetzt haben wir die CSS-Datei, aber FastAPI kennt sie noch nicht. Um dies zu beheben, müssen wir das static-Verzeichnis in main.py "mounten".

Öffnen Sie main.py und ändern Sie es wie folgt:

# main.py
from fastapi import FastAPI, Request
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse
import markdown
from fastapi.staticfiles import StaticFiles # 1. StaticFiles importieren

app = FastAPI()

# 2. Das statische Verzeichnis einbinden
# Dies teilt FastAPI mit, dass jede Anfrage, die mit /static beginnt,
# nach Dateien im Ordner "static" suchen soll
app.mount("/static", StaticFiles(directory="static"), name="static")


templates = Jinja2Templates(directory="templates")


# --- Home-Route (unverändert) ---
@app.get("/", response_class=HTMLResponse)
async def root(request: Request):
    context = {
        "request": request,
        "page_title": "Hallo, Jinja2!"
    }
    return templates.TemplateResponse("index.html", context)


# --- Doc-Route (wird als nächstes geändert) ---
@app.get("/docs/hello", response_class=HTMLResponse)
async def get_hello_doc(request: Request):
    md_file_path = "docs/hello.md"
    try:
        with open(md_file_path, "r", encoding="utf-8") as f:
            md_content = f.read()
    except FileNotFoundError:
        return HTMLResponse(content="<h1>404 - Dokument nicht gefunden</h1>", status_code=404)

    # Noch unverändert, wir werden es im nächsten Schritt ändern
    html_content = markdown.markdown(md_content)

    context = {
        "request": request,
        "page_title": "Hallo, Markdown!",
        "content": html_content
    }
    return templates.TemplateResponse("doc.html", context)

Schritt 5: Das CSS in die HTML-Vorlage einbinden

Ändern Sie templates/doc.html und fügen Sie ein <link>-Tag in den <head> ein, damit die HTML-Seite das CSS zur Codehervorhebung laden kann:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>{{ page_title }} - Meine Docs-Site</title>

    <link
      rel="stylesheet"
      href="{{ url_for('static', path='css/highlight.css') }}"
    />
  </head>
  <body>
    <h1>{{ page_title }}</h1>

    <hr />

    <div class="doc-content">{{ content | safe }}</div>
  </body>
</html>

Schritt 6: Markdown-Erweiterungen aktivieren

Als letzten Schritt kehren wir zu main.py zurück und weisen die Bibliothek python-markdown an, die Erweiterung codehilite während der Konvertierung zu verwenden.

Wir benötigen auch die Erweiterung fenced_code, die verwendet wird, um Inhalt in dreifachen Backticks (```) als Codeblöcke darzustellen, was eine notwendige Bedingung für die Anzeige der Syntaxhervorhebung ist.

Ändern Sie die Routenfunktion get_hello_doc in main.py:

# main.py

# ... (andere Importe und App-Instanz unverändert) ...

# ... (app.mount und templates-Instanz unverändert) ...

# ... (root-Home-Route unverändert) ...


@app.get("/docs/hello", response_class=HTMLResponse)
async def get_hello_doc(request: Request):
    """
    Liest, parst und rendert das Dokument hello.md (mit Syntaxhervorhebung)
    """
    md_file_path = "docs/hello.md"

    try:
        with open(md_file_path, "r", encoding="utf-8") as f:
            md_content = f.read()
    except FileNotFoundError:
        return HTMLResponse(content="<h1>404 - Dokument nicht gefunden</h1>", status_code=404)

    # Wichtige Änderung: Markdown-Erweiterungen aktivieren
    # 1. fenced_code: Unterstützt ``` Syntax
    # 2. codehilite: Aktiviert Syntaxhervorhebung (verwendet automatisch Pygments)
    extensions = ['fenced_code', 'codehilite']
    html_content = markdown.markdown(md_content, extensions=extensions)

    context = {
        "request": request,
        "page_title": "Hallo, Markdown!",
        "content": html_content
    }

    return templates.TemplateResponse("doc.html", context)

Schritt 7: Ausführen und Testen

Führen Sie uvicorn main:app --reload aus, um den Server zu starten.

Besuchen Sie nun erneut http://127.0.0.1:8000/docs/hello.

Sie werden feststellen, dass der Python-Codeblock in hello.md jetzt die Syntaxhervorhebung im monokai-Thema aufweist. Sie können auch versuchen, die Parameter bei der Generierung des CSS zu ändern, um die Auswirkungen anderer Hervorhebungsthemen zu sehen.

Bereitstellung des Projekts online

Eine Dokumentationsseite ist dazu gedacht, von jedem besucht zu werden, daher reicht es nicht aus, sie nur lokal auszuführen. Als Nächstes können wir sie online bereitstellen.

Eine einfache Bereitstellungsoption ist die Verwendung von Leapcell. Es ist eine Web-App-Hosting-Plattform, die Projekte in verschiedenen Sprachen und Frameworks hosten kann, einschließlich FastAPI, natürlich.

Befolgen Sie die folgenden Schritte:

1.Registrieren Sie ein Konto auf der Website.

2.Committen Sie Ihr Projekt auf GitHub. Für die Schritte können Sie die offizielle Dokumentation von GitHub konsultieren. Leapcell zieht den Code später aus Ihrem GitHub-Repository.

3.Klicken Sie auf der Leapcell-Seite auf "Create Service".

4.Nachdem Sie Ihr FastAPI-Repo ausgewählt haben, sehen Sie, dass Leapcell die notwendigen Konfigurationen automatisch ausgefüllt hat.

5.Klicken Sie unten auf "Submit", um die Bereitstellung zu starten. Die Bereitstellung wird schnell abgeschlossen und Sie zurück zur Startseite der Bereitstellung geleitet. Hier sehen wir, dass Leapcell eine Domain bereitgestellt hat. Dies ist die Online-Adresse Ihres Blogs.

Fazit und nächste Schritte

Mit Syntaxhervorhebung sieht Ihre Dokumentationsseite viel professioneller aus.

Aber es gibt noch ein Problem: Der Seitentitel ({{ page_title }}) in der doc.html-Vorlage ist immer noch fest im Routenfunktion in main.py ("page_title": "Hallo, Markdown!") kodiert, anstatt aus der Markdown-Datei abgerufen zu werden.

Das ist sehr unflexibel. Der richtige Ansatz ist, dass dieser Titel auch aus der hello.md-Datei selbst gelesen wird.

Im nächsten Artikel werden wir Frontmatter (zur Definition von Artikelmetadaten wie title, date usw.) in unseren Markdown-Dateien einführen und das Parsen und Lesen von Frontmatter in unserem Projekt implementieren, um Festkodierungen in unserem Code zu vermeiden.