Eine Docusaurus-ähnliche Seite mit FastAPI erstellen: Schritt 1 - HTML-Vorlage
Grace Collins
Solutions Engineer · Leapcell

Es gibt viele Tools zur Erstellung von Dokumentations-Websites, aber wie Sie wahrscheinlich festgestellt haben, ist keines davon für alle Ihre spezifischen Bedürfnisse geeignet und gleichzeitig einfach genug zu bedienen.
Wenn das der Fall ist, warum bauen Sie nicht Ihre eigene?
In der folgenden Artikelreihe werden wir schrittweise eine Dokumentations-Website ähnlich wie Docusaurus erstellen.
Dies ist der erste Artikel. Wir beginnen mit dem Erstellen eines einfachen Backend-Dienstes, der eine dynamische HTML-Vorlagenseite zurückgibt.
Schritt 1: Umgebungs-Setup und Installation von Abhängigkeiten
Zuerst müssen wir ein Projektverzeichnis erstellen und die notwendigen Abhängigkeiten installieren.
Erstellen Sie das Projektverzeichnis:
mkdir fastapi-docs-site cd fastapi-docs-site
Installieren Sie die Kernabhängigkeiten: Wir werden drei Schlüsselbibliotheken installieren:
fastapi: Unser Web-Framework.uvicorn[standard]: Der ASGI-Server zum Ausführen von FastAPI.jinja2: Die Engine, die zum Rendern von HTML-Vorlagen verwendet wird.
pip install fastapi "uvicorn[standard]" jinja2
Schritt 2: Erstellen des Projektgerüsts
Erstellen Sie als Nächstes die folgenden Dateien und Ordner im Stammverzeichnis von fastapi-docs-site:
fastapi-docs-site/
├── main.py           # Unsere Haupt-FastAPI-Anwendungsdatei
├── static/           # Zum Speichern von statischen Dateien wie CSS, JS, Bilder
└── templates/        # Zum Speichern von Jinja2 HTML-Vorlagen
main.py: Hier wird die gesamte Logik und die Routen unserer FastAPI-Anwendung gespeichert.templates/: Jinja2 sucht hier standardmäßig nach HTML-Vorlagendateien.static/: FastAPI wird dieses Verzeichnis verwenden, um statische Dateien bereitzustellen (wir werden dies in einem zukünftigen Artikel verwenden).
Schritt 3: Schreiben Sie Ihre erste FastAPI-App (JSON-Version)
Bevor wir mit dem Rendern von Vorlagen beginnen, stellen wir zunächst sicher, dass FastAPI selbst korrekt funktioniert.
Öffnen Sie main.py und geben Sie den folgenden Basiscode ein:
# main.py from fastapi import FastAPI # Instanziieren Sie die FastAPI-App app = FastAPI() @app.get("/") async def root(): """ Root-Route, gibt eine einfache JSON-Antwort zurück """ return {"message": "Hello FastAPI"}
Öffnen Sie Ihr Terminal, stellen Sie sicher, dass Sie sich im Stammverzeichnis von fastapi-docs-site befinden, und führen Sie aus:
uvicorn main:app --reload
main:appbezieht sich auf dieapp = FastAPI()-Instanz, die inmain.pyerstellt wurde.--reload: Dieser Parameter überwacht Ihre Codeänderungen und startet den Server automatisch neu.
Öffnen Sie nun Ihren Browser und besuchen Sie http://127.0.0.1:8000. Sie sollten sehen:
{ "message": "Hello FastAPI" }
Schritt 4: Konfigurieren Sie die Jinja2-Vorlagen-Engine
Großartig, der Server läuft. Aber wir wollen HTML, nicht JSON.
Wir müssen FastAPI mitteilen, wie das templates-Verzeichnis gefunden und verwendet wird.
Ändern Sie main.py:
# main.py from fastapi import FastAPI # Importieren Sie Jinja2Templates from fastapi.templating import Jinja2Templates # Instanziieren Sie die FastAPI-App app = FastAPI() # Wichtiger Schritt: Konfigurieren Sie das Vorlagenverzeichnis # Der String "templates" muss mit dem von Ihnen erstellten Ordnernamen übereinstimmen templates = Jinja2Templates(directory="templates") @app.get("/") async def root(): # Behalten Sie dies vorerst bei, wir werden es im nächsten Schritt ändern return {"message": "Hello FastAPI"}
Schritt 5: Erstellen Sie unsere erste HTML-Vorlage
Erstellen Sie im Ordner templates/ eine neue Datei: index.html.
<!DOCTYPE html> <html lang="en"> <head> <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0" /> <title>My Docs Site</title> </head> <body> <h1>{{ page_title }}</h1> <p>Welcome to our first dynamic page!</p> </body> </html>
Beachten Sie <h1>{{ page_title }}</h1>. Das ist kein reines HTML. {{ ... }} ist die Variablensyntax von Jinja2. Wir werden bald einen Wert (wie "Homepage") dynamisch von unserem FastAPI-Backend an diese page_title-Variable übergeben.
Schritt 6: Rendern der Vorlage mit TemplateResponse
Letzter Schritt: Ändern wir die Root-Route / so, dass sie kein JSON mehr zurückgibt, sondern stattdessen unsere index.html-Vorlage rendert.
Dazu müssen wir die folgenden Werkzeuge importieren:
Request: Dies ist erforderlich, damit Jinja2 korrekt URLs und Kontext erstellen kann.HTMLResponse: Eine von FastAPI bereitgestellte Antwortklasse speziell für die Rückgabe von HTML.
Ändern Sie main.py wie folgt:
# main.py from fastapi import FastAPI, Request # Importieren Sie Request from fastapi.templating import Jinja2Templates from fastapi.responses import HTMLResponse # Importieren Sie HTMLResponse app = FastAPI() templates = Jinja2Templates(directory="templates") # Hinweis: Die Signatur der Routenfunktion enthält jetzt request: Request @app.get("/", response_class=HTMLResponse) async def root(request: Request): """ Root-Route, gibt die gerenderte HTML-Vorlage zurück """ # 1. Der Name der Vorlagendatei template_name = "index.html" # 2. Der an die Vorlage zu übergebende Kontext # "request" ist erforderlich # "page_title" ist unsere benutzerdefinierte Variable, die {{ page_title }} im HTML entspricht context = { "request": request, "page_title": "Hello, Jinja2!" } return templates.TemplateResponse(template_name, context)
Wenn Sie --reload aktiviert hatten, sollte Ihr Server automatisch neu gestartet worden sein.
Aktualisieren Sie die Seite http://127.0.0.1:8000.
Sie werden feststellen, dass das JSON verschwunden ist, ersetzt durch eine gerenderte HTML-Seite, und der Inhalt des <h1>-Tags wurde dynamisch ersetzt.

Bereitstellung des Projekts online
Eine Dokumentations-Website soll von jedem besucht werden können, 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 nachstehenden Schritte:
1.Registrieren Sie ein Konto auf der Website.
2.Committen Sie Ihr Projekt nach GitHub. Sie können die offizielle Dokumentation von GitHub für die Schritte konsultieren. Leapcell wird den Code später aus Ihrem GitHub-Repository ziehen.
3.Klicken Sie auf der Leapcell-Seite auf "Create Service".

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

5.Klicken Sie unten auf "Submit" (Absenden), um die Bereitstellung zu starten. Die Bereitstellung wird schnell abgeschlossen und Sie werden zur Homepage der Bereitstellung weitergeleitet. Hier sehen Sie, dass Leapcell eine Domain bereitgestellt hat. Dies ist die Online-Adresse Ihres Blogs.

Zusammenfassung
Glückwunsch! Sie haben den ersten Schritt erfolgreich gemeistert: Ein FastAPI-Projekt eingerichtet und grundlegendes HTML-Vorlagen-Rendering implementiert.
Wenn Sie andere Dokumentations-Websites verwendet haben, haben Sie wahrscheinlich bemerkt, dass deren Inhalte nicht manuell in HTML geschrieben sind. Sie schreiben einfach Markdown, und die Webseiten werden automatisch generiert.
Im nächsten Artikel werden wir diese Kernfunktion implementieren: das dynamische Lesen einer echten Markdown-Datei (z. B. docs/hello.md), das Parsen in HTML und das Einbetten in unsere Webvorlage.
