Schritt 7: Custom Domain einrichten (optional)
Statt interne-doku.pages.dev kannst du eine eigene Domain nutzen, z. B. docs.firma.de.
Voraussetzung
- Die Domain muss bei Cloudflare liegen (Nameserver auf Cloudflare zeigen).
- Das Pages-Projekt ist angelegt und deployed.
Anleitung
- Im Cloudflare Dashboard die Suchleiste oben nutzen und nach dem Pages-Projekt suchen (z. B.
interne-doku). Es erscheint unter Workers & Pages. - Im Projekt: Custom domains → Set up a custom domain.
- Subdomain eingeben, z. B.
docs.firma.de. - Cloudflare erstellt den CNAME-Record automatisch (da die Domain bereits bei Cloudflare liegt).
- Klicke auf Check DNS records — sollte sofort oder innerhalb weniger Minuten verifiziert werden.
- Prüfe unter DNS → Records, dass der CNAME-Eintrag auf Proxied steht. Proxied muss aktiv sein, damit SSL, Caching und Access funktionieren.
mkdocs.yml anpassen
Aktualisiere die site_url in mkdocs.yml:
site_url: https://docs.firma.de/
Dann committen und pushen:
git add mkdocs.yml
git commit -m "site_url auf Custom Domain angepasst"
git push
Die site_url muss stimmen, sonst funktionieren die Suchfunktion und absolute Links nicht korrekt.
Cloudflare Access anpassen
Falls du in Schritt 6 Access eingerichtet hast: Stelle sicher, dass die Application-Domain auf deine Custom Domain zeigt. Die pages.dev-URL bleibt weiterhin erreichbar — sichere auch diese per Access ab (siehe Schritt 6).
DNS-Propagation
Wenn die Domain bereits bei Cloudflare liegt, geht die Verifikation normalerweise sofort. Falls der CNAME-Record frisch angelegt wurde, kann es aber ein paar Minuten dauern.
Typische Probleme
| Problem | Lösung |
|---|---|
| Domain nicht verfügbar | Die Domain muss bei Cloudflare als Zone eingerichtet sein (Nameserver müssen auf Cloudflare zeigen) |
| SSL-Fehler | Warte ein paar Minuten — Cloudflare stellt das Zertifikat automatisch aus |
| Safari findet den Server nicht | Safari cached DNS aggressiv. Safari komplett beenden (Cmd+Q, nicht nur Fenster schließen) und neu öffnen. Chrome funktioniert meistens sofort. |
| Seite lädt in Chrome aber nicht Safari | Gleiches DNS-Cache-Problem — Safari beenden und neu starten |
| Alte URL funktioniert nicht mehr | interne-doku.pages.dev bleibt weiterhin erreichbar, es sei denn du deaktivierst es explizit |
Fertig
Das Setup ist abgeschlossen. Ab jetzt aktualisierst du die Doku einfach per Push:
# Markdown bearbeiten, dann:
git add docs/
git commit -m "Doku: Abschnitt X ergänzt"
git push
Der Workflow baut und deployt automatisch innerhalb von ca. 1 Minute.