Erstellen einer Docusaurus-ähnlichen Website mit FastAPI: Schritt 5 - Statische Dateien bereitstellen

Im vorherigen Artikel haben wir die Unterstützung für das Parsen von Markdown Frontmatter hinzugefügt. Dies ermöglicht die Definition unserer Dokumentmetadaten (wie den Titel) innerhalb der Markdown-Datei zusammen mit dem Inhalt, wodurch Hardcoding vermieden wird.

Neben Text und Code enthält ein Dokument normalerweise statische Ressourcen wie Bilder.

Derzeit wird ein Bild in hello.md nicht angezeigt, wenn Sie es referenzieren. In diesem Artikel werden wir dieses Problem lösen, indem wir FastAPI ermöglichen, statische Ressourcen wie Bilder, die in unseren Markdown-Dateien referenziert werden, korrekt zu handhaben und bereitzustellen.

Warum wird das Bild nicht angezeigt?

Hier ist ein Markdown-Dokument, das ein Bild leapcell-logo.png enthält:

# Hallo, Markdown!

Hier ist ein Logo:
![Leapcell Logo](./leapcell-logo.png)

Wenn Sie den Server ausführen und dieses Dokument besuchen, wird das Bild nicht geladen.

Dies liegt daran, dass der Bildpfad ./leapcell-logo.png lautet. Wenn der Browser diesen Pfad von der Seite /docs/hello anfordert, ist die tatsächliche URL, die er anfordert, http://127.0.0.1:8000/docs/leapcell-logo.png.

In unserer FastAPI-Anwendung sind jedoch keine Routen oder gemounteten Verzeichnisse konfiguriert, um die Anfrage /docs/leapcell-logo.png zu bearbeiten, sodass das Bild nicht geladen wird.

Schritt 2: Konvention für Dokumentenressourcen erstellen

Wir brauchen eine Möglichkeit, diese Bilder bereitzustellen. Der einfache Ansatz wäre, alle Bilder im Ordner static zu platzieren, aber eine bessere Praxis ist es, Inhaltsressourcen (wie leapcell-logo.png) vom Hauptverzeichnis static zu trennen und sie in einem dedizierten Ordner zu platzieren, z. B. docs/assets.

Aktualisieren Sie die Verzeichnisstruktur wie folgt:

fastapi-docs-site/
├── docs/
│   ├── assets/           <-- Neu
│   │   └── leapcell-logo.png   <-- Ressourcendatei
│   └── hello.md
├── main.py
├── static/
│   └── css/
│       └── highlight.css
└── templates/

Schritt 3: Verzeichnis für Dokumentenressourcen in FastAPI mounten

Nun müssen wir FastAPI mitteilen: "Jede Anfrage, die mit /docs/assets/ beginnt, soll nach Dateien im Ordner docs/assets/ suchen."

Ö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

app = FastAPI()

# Dies ist unser neu hinzugefügtes "assets"-Verzeichnis für Dokumenteninhalte
# Hinweis: Der Mount-Pfad ist "/docs/assets", das physische Verzeichnis ist "docs/assets"
app.mount("/docs/assets", StaticFiles(directory="docs/assets"), name="doc_assets")

# Andere Codes bleiben unverändert

Beachten Sie, dass wir /docs/assets und nicht /docs mounten. Dies dient der Sicherheit: Wir wollen nur Ressourcen wie Bilder im Ordner assets verfügbar machen und vermeiden, die .md-Quelldateien aus dem Verzeichnis docs/ verfügbar zu machen.

Schritt 4: Bildlink in Markdown aktualisieren

Jetzt können wir das Bild in Markdown gemäß unserem konfigurierten statischen Pfad referenzieren.

Bearbeiten Sie docs/hello.md:

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

# Hallo, Markdown!

Dies ist das erste Markdown-Dokument, das wir mit FastAPI gerendert haben.

Hier ist ein Logo:

![Leapcell Logo](./assets/leapcell-logo.png)

Schritt 5: Ausführen und Testen

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

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

Sie werden sehen, dass das hinzugefügte Bild leapcell-logo.png nun korrekt auf der Seite gerendert wird.

Zusammenfassung

Mit einigen einfachen Konfigurationen und Konventionen haben wir unsere Markdown-Dokumente so eingerichtet, dass sie Bilder enthalten und korrekt rendern.

Wenn wir weitere Dokumente hinzufügen, sollte unsere Website eine Seitenleiste haben, um alle verfügbaren Dokumente aufzulisten. Dies sollte natürlich auch automatisch generiert werden.

Im nächsten Artikel werden wir diese Seitenleiste dynamisch durch Scannen des Verzeichnisses docs/ generieren und das Layout der Website auf "linke Seitenleiste, rechter Inhalt" umstellen.

Sonstiges

Nachdem Sie Ihre Website erstellt haben, möchten Sie sie vielleicht online stellen, damit andere sie sehen können. Aber die meisten Cloud-Plattformen sind teuer, und es lohnt sich nicht, hohe Preise für ein Übungsprojekt wie dieses 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 eine großzügige kostenlose Stufe, mit der Sie bis zu 20 Projekte kostenlos bereitstellen können.