Schritt 1: Lokale Vorschau testen
Bevor du irgendetwas bei Cloudflare einrichtest, prüfe ob die Doku lokal korrekt baut. So erkennst du Fehler sofort, statt sie erst im CI zu sehen.
Voraussetzung
- Docker muss installiert und gestartet sein.
Anleitung
-
Öffne ein Terminal im Projektverzeichnis.
-
Starte den MkDocs-Dev-Server:
bash
docker run --rm -it -p 8000:8000 -v "${PWD}:/docs" squidfunk/mkdocs-material:9 serve --dev-addr 0.0.0.0:8000
-
Öffne im Browser: http://127.0.0.1:8000
-
Du solltest die Startseite „Willkommen" sehen.
-
Teste Live-Reload: Ändere etwas in
docs/index.md, speichere — die Seite aktualisiert sich automatisch. -
Beende den Server mit Ctrl+C.
Was passiert hier?
docker runstartet den offiziellen MkDocs-Material-Container.-v "${PWD}:/docs"mounted dein Projektverzeichnis in den Container.servestartet einen lokalen Webserver mit Live-Reload.- Es wird kein Python auf deinem Rechner installiert — alles läuft im Container.
Typische Probleme
| Problem | Lösung |
|---|---|
| Port 8000 belegt | Anderen Port nutzen: -p 8080:8000, dann http://127.0.0.1:8080 |
| Docker nicht gefunden | Docker Desktop installieren und starten |
failed to connect to the docker API / docker.sock: no such file or directory |
Docker Desktop ist nicht gestartet — öffne es über Launchpad oder den Applications-Ordner und warte bis es läuft |
| Permission denied | Unter Linux ggf. sudo vor den Docker-Befehl setzen oder User zur docker-Gruppe hinzufügen |