Erstellen einer Docusaurus-ähnlichen Website mit FastAPI: Schritt 4 – Parsen von Frontmatter

Im vorherigen Artikel haben wir die Syntaxhervorhebung für unsere Markdown-Codeblöcke hinzugefügt.

Aber Sie haben vielleicht bemerkt, dass der Seitentitel ({{ page_title }}) in der Routenfunktion main.py ("page_title": "Hello, Markdown!") immer noch fest codiert ist. Das ist sehr unflexibel. Bedeutet das, dass wir den Code jedes Mal ändern müssen, wenn wir ein neues Dokument hinzufügen?

Eine Dokumentations-Website muss flexibel sein und es ermöglichen, Artikel jederzeit hinzuzufügen oder zu entfernen. Die Metadaten eines Artikels – wie Titel, Autor und Datum – sollten in der Markdown-Datei selbst definiert werden, genau wie der Inhalt.

In diesem Artikel werden wir Frontmatter (eine gängige Spezifikation für die Definition von Metadaten am Anfang einer Markdown-Datei) einführen und FastAPI das Parsen ermöglichen, damit wir Metadaten dynamisch laden können.

Schritt 1: Installieren der Frontmatter-Parsing-Bibliothek

Wir werden python-frontmatter verwenden, um das Frontmatter und den Markdown-Inhalt aus unseren Dateien zu trennen und zu parsen.

Installieren Sie es mit dem folgenden Befehl:

pip install python-frontmatter

Schritt 2: Hinzufügen von Frontmatter zu unserem Markdown-Dokument

Als Nächstes modifizieren wir die Datei docs/hello.md, um Frontmatter ganz oben hinzuzufügen.

Ein Frontmatter-Block wird durch dreifache Bindestriche (---) umschlossen.

Aktualisieren Sie docs/hello.md:

---
title: Hello, Frontmatter!
author: FastAPI Developer
date: 2025-11-09
---

... (Restlicher Markdown-Inhalt)

Wir haben hier drei Metadatenfelder definiert: title, author und date. Sie können bei Bedarf weitere Felder hinzufügen. Das Feld title wird letztendlich als page_title des Artikels verwendet.

Schritt 3: main.py zum Parsen von Frontmatter modifizieren

Nun modifizieren wir die Routenfunktion get_hello_doc, um die Bibliothek frontmatter zu verwenden, um die Datei zu laden, anstatt nur open().read().

Die Funktion frontmatter.load() parst die Datei in zwei Teile:

1. post.metadata: Ein Dictionary, das alle Frontmatter-Daten enthält (z. B. {'title': 'Hello, Frontmatter!', ...}).
2. post.content: Ein String, der nur den Hauptteil des Markdown-Inhalts enthält.

Ö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
import frontmatter  # 1. Importieren Sie die Frontmatter-Bibliothek

app = FastAPI()

app.mount("/static", StaticFiles(directory="static"), name="static")

templates = Jinja2Templates(directory="templates")


# --- Home-Route (unverändert) ---
@app.get("/", response_class=HTMLResponse)
def root(request: Request):
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!" # (Chinesisch beibehalten zur Übereinstimmung mit dem Bild, aber "Hello, Jinja2!" ist das englische Äquivalent)
    }
    return templates.TemplateResponse("index.html", context)


# --- 2. Modifizieren Sie die Dokumenten-Route ---
@app.get("/docs/hello", response_class=HTMLResponse)
def get_hello_doc(request: Request):
    """
    Liest, parst (einschließlich Frontmatter) und rendert das hello.md-Dokument
    """
    md_file_path = "docs/hello.md"

    try:
        # 3. Verwenden Sie frontmatter.load, um die Datei zu lesen und zu parsen
        post = frontmatter.load(md_file_path)
    except FileNotFoundError:
        return HTMLResponse(content="<h1>404 - Dokument nicht gefunden</h1>", status_code=404)
    except Exception as e:
        # Fügen Sie eine allgemeine Fehlerbehandlung für den Fall von fehlerhaftem YAML /} hinzu
        return HTMLResponse(content=f"<h1>500 - Parse-Fehler: {e}</h1>", status_code=500)

    # 4. Extrahieren Sie Metadaten und Inhalt
    metadata = post.metadata
    md_content = post.content # Dies ist der reine Markdown-Inhalt

    # 5. Konvertieren Sie nur den Markdown-Inhalt
    extensions = ['fenced_code', 'codehilite']
    html_content = markdown.markdown(md_content, extensions=extensions)

    # 6. Rufen Sie page_title dynamisch aus den Metadaten ab
    #    Verwenden Sie .get(), um Abstürze zu vermeiden, falls der 'title'-Schlüssel fehlt
    page_title = metadata.get('title', 'Ungesetteltes Dokument')

    context = {
        "request": request,
        "page_title": page_title,    # Ersetzte den fest codierten Wert
        "content": html_content
    }

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

Schritt 4: 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 sehen, dass der Titel des Browser-Tabs und die <h1>-Überschrift auf der Seite nicht mehr "Hello, Markdown!" sind, sondern durch "Hello, Frontmatter!" ersetzt wurden, das wir gerade im Frontmatter der Datei hello.md definiert haben.

Fazit und nächste Schritte

Durch die Einführung von Frontmatter und der Logik zum Parsen davon sind unsere Artikel nun vollständig von der Website entkoppelt.

Neben Markdown enthält eine Website auch statische Dateien wie Bilder. Wie können wir FastAPI diese statischen Dateien korrekt bereitstellen lassen, damit sie online zugänglich sind?

Im nächsten Artikel werden wir dieses Problem lösen: Umgang mit statischen Assets (wie Bildern), auf die in Markdown-Dateien verwiesen wird, damit sie von FastAPI korrekt bereitgestellt und auf der endgültigen Webseite angezeigt werden können.

Sonstiges

Nachdem Sie Ihre Website erstellt haben, möchten Sie sie möglicherweise online stellen, damit andere sie sehen können. Aber die meisten Cloud-Plattformen sind teuer, und es lohnt sich nicht, für ein Übungsprojekt wie dieses einen hohen Preis zu zahlen.

Gibt es eine wirtschaftlichere Möglichkeit, sie bereitzustellen? Sie können Leapcell ausprobieren. Es unterstützt die Bereitstellung mehrerer Sprachen wie Python, Node.js, Go und Rust und bietet jeden Monat ein großzügiges kostenloses Kontingent, mit dem Sie bis zu 20 Projekte kostenlos bereitstellen können.