Erstellen einer Docusaurus-ähnlichen Website mit FastAPI: Schritt 2 – Markdown rendern

Im vorherigen Artikel haben wir einen FastAPI-Service eingerichtet und Jinja2 verwendet, um eine dynamische HTML-Vorlage zu rendern.

Wenn Sie andere Dokumentations-Website-Tools verwendet haben, wissen Sie, dass sie alle funktionieren, indem sie Markdown schreiben, das sie dann zum Generieren von HTML-Inhalten verwenden, anstatt HTML von Hand zu schreiben.

In diesem Artikel werden wir genau diese Funktion implementieren: eine lokale .md-Datei lesen, sie in HTML parsen und in unsere Web-Vorlage einfügen.

Schritt 1: Installieren einer Markdown-Parsing-Bibliothek

Wir benötigen ein Werkzeug, um Markdown-Text in eine HTML-Zeichenkette umzuwandeln. Eine beliebte Bibliothek dafür ist python-markdown.

Installieren Sie sie, indem Sie den folgenden Befehl ausführen:

pip install markdown

Schritt 2: Erstellen unseres ersten Markdown-Dokuments

Gemäß Konvention werden wir alle unsere Quell-Dokumente in einem neuen Ordner docs/ speichern.

Erstellen Sie zuerst einen Ordner docs im Stammverzeichnis Ihres Projekts und dann eine Datei hello.md darin.

Aktualisierte Projektstruktur:

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

Bearbeiten von docs/hello.md: Öffnen Sie diese neue Datei und schreiben Sie etwas Markdown-Inhalt, damit wir es später testen können.

# Hallo, Markdown!

Dies ist unser erstes Markdown-Dokument, das mit FastAPI gerendert wird.

Hier ist ein Beispiel für einen Codeblock (obwohl er noch keine Syntaxhervorhebung hat):

```python
def say_hello():
    print("Hello from FastAPI!")
```

  - Dies ist ein Listenelement
  - Dies ist ein weiteres Listenelement

Schritt 3: Erstellen einer Vorlage zum Rendern von Dokumenten

Die Vorlage templates/index.html, die wir im letzten Artikel erstellt haben, ist unsere Homepage. Jetzt brauchen wir eine eigene Vorlage, um den Inhalt dieser Markdown-Datei anzuzeigen.

Erstellen Sie eine neue Datei im Ordner templates/ mit dem Namen doc.html.

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

    <hr />

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

{{ content | safe }} sagt Jinja2: „Der Inhalt dieser content-Variablen ist sicheres HTML. Bitte rendern Sie ihn direkt und maskieren Sie ihn nicht.“

Schritt 4: Erstellen der Markdown-Rendering-Route

Als nächstes ändern wir main.py, um eine neue Route für unsere Markdown-Datei hinzuzufügen, zum Beispiel /docs/hello.

Sie wird folgende Aktionen ausführen:

Den Inhalt der Datei docs/hello.md lesen.
Die markdown-Bibliothek importieren.
Die Funktion markdown.markdown() verwenden, um den Dateiinhalt in eine HTML-Zeichenkette zu konvertieren.
Diese HTML-Zeichenkette als content-Variable an die Vorlage doc.html übergeben.

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

# main.py
from fastapi import FastAPI, Request
from fastapi.templating import Jinja2Templates
from fastapi.responses import HTMLResponse
import markdown  # 1. Importieren Sie die markdown-Bibliothek

app = FastAPI()

templates = Jinja2Templates(directory="templates")


# --- Dies ist die Homepage-Route aus dem vorherigen Artikel ---
@app.get("/", response_class=HTMLResponse)
def root(request: Request):
    """
    Root-Route, gibt die gerenderte HTML-Vorlage zurück
    """
    context = {
        "request": request,
        "page_title": "Hello, Jinja2!"
    }
    return templates.TemplateResponse("index.html", context)


# --- 2. Dies ist unsere neue Dokumentationsroute ---
@app.get("/docs/hello", response_class=HTMLResponse)
def get_hello_doc(request: Request):
    """
    Liest, parst und rendert das Dokument hello.md
    """

    # 3. Hartkodieren Sie den Pfad zur Markdown-Datei
    #    (Wir werden dies in einem zukünftigen Artikel dynamisch machen)
    md_file_path = "docs/hello.md"

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

    # 4. Verwenden Sie die markdown-Bibliothek, um es in HTML zu konvertieren
    html_content = markdown.markdown(md_content)

    # 5. Bereiten Sie den Vorlagenkontext vor
    #     Beachten Sie, dass wir jetzt doc.html rendern
    context = {
        "request": request,
        "page_title": "Hello, Markdown!", # Titel vorübergehend hartkodiert
        "content": html_content         # Übergeben Sie das konvertierte HTML
    }

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

Schritt 5: Ausführen und testen

Starten Sie Ihren Server, indem Sie uvicorn main:app --reload ausführen.

Besuchen Sie in Ihrem Browser diese URL: http://127.0.0.1:8000/docs/hello

Sie sollten den Inhalt von docs/hello.md erfolgreich als HTML-Seite gerendert sehen!

Bereitstellen des Projekts online

Eine Dokumentationsseite soll von allen besucht 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 Plattform zum Hosten von Webanwendungen, die Projekte in verschiedenen Sprachen und Frameworks hosten kann, einschließlich FastAPI.

Befolgen Sie die unten stehenden Schritte:

1.Registrieren Sie ein Konto auf der Website.

2.Commiten Sie Ihr Projekt nach GitHub. Sie können die offizielle GitHub-Dokumentation für die Schritte einsehen. Leapcell wird den Code später aus Ihrem GitHub-Repository ziehen.

3.Klicken Sie auf der Leapcell-Seite auf „Service erstellen“.

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

5.Klicken Sie unten auf „Senden“, um die Bereitstellung zu starten. Die Bereitstellung wird schnell abgeschlossen und Sie werden zur Bereitstellungs-Homepage zurückgeleitet. Hier sehen wir, dass Leapcell eine Domain bereitgestellt hat. Dies ist die Online-Adresse Ihres Blogs.

Zusammenfassung und nächste Schritte

Mit diesem Artikel haben wir die Kernfunktion einer Dokumentationsseite implementiert: dynamische Markdown-zu-HTML-Konvertierung.

Sie haben wahrscheinlich den Python-Codeblock in hello.md bemerkt. Obwohl er korrekt als Code gerendert wurde, sieht er schlicht aus, hat keine Farbgestaltung und ist schwer zu lesen.

Das ist eindeutig nicht die Erfahrung, die eine Dokumentationsseite bieten sollte.

Im nächsten Artikel werden wir dieses Problem lösen: Hinzufügen von Syntaxhervorhebungen zu unseren gerenderten Markdown-Codeblöcken.