Zum Inhalt

MkDocs Deployment auf Cloudflare Pages

⚡️ Schnellstart - Manuelles Deployment

Voraussetzungen

npm install -g wrangler
wrangler login

Deployment

# 1. Build static site
python3 -m mkdocs build --strict

# 2. Deploy to Cloudflare Pages
npx wrangler pages deploy site --project-name=solarlog-docs

# Fertig! URL: https://solarlog-docs.pages.dev

🚀 Automatisches Deployment (GitHub Actions)

Option 1: Cloudflare Pages Dashboard (Empfohlen)

  1. Push Code zu GitHub 

    git add -A
git commit -m "feat: Add MkDocs static site"
git push origin main

  2. Cloudflare Pages Setup

  3. Gehe zu: https://dash.cloudflare.com/pages
  4. Klicke "Create a project"
  5. Wähle "Connect to Git"

  6. Wähle dein Repository

  7. Build Konfiguration 

    Framework preset: None
Build command: pip3 install mkdocs mkdocs-material && mkdocs build --strict
Build output directory: site
Root directory: /

  8. Environment Variables (optional)

  9. Keine erforderlich

  10. Deploy!

  11. Jeder Push zu main triggert automatisch einen neuen Build
  12. URL: https://solarlog-docs.pages.dev

Option 2: GitHub Actions Workflow

Siehe .github/workflows/deploy-docs.yml für automatisches Deployment bei jedem Push.

🌐 Custom Domain Setup

Cloudflare Pages Domain hinzufügen

  1. In Cloudflare Pages Dashboard
  2. Gehe zu deinem Project → Settings → Custom domains

  3. Klicke "Add a custom domain"

  4. Domain konfigurieren 

    Domain: docs.karma.organic
oder
Domain: solarlog-docs.karma.organic

  5. DNS automatisch konfiguriert

  6. Cloudflare erstellt automatisch CNAME Record
  7. SSL/TLS automatisch aktiviert

  8. CDN automatisch aktiviert

  9. Fertig!

  10. URL: https://docs.karma.organic
  11. Automatische HTTPS
  12. Weltweit auf 300+ Edge-Servern

Nach Deployment die Links in der React App aktualisieren:

frontend-web/src/components/AppBar.tsx: 

// Vorher:
href="http://localhost:8001"

// Nachher:
href="https://docs.karma.organic"
// oder
href="https://solarlog-docs.pages.dev"

frontend-web/src/components/About.tsx: 

// Links zur Dokumentation aktualisieren
href="https://docs.karma.organic"

🔄 Lokale Entwicklung

# Serve docs lokal (mit Live-Reload)
python3 -m mkdocs serve --dev-addr 127.0.0.1:8001

# Build und Preview
python3 -m mkdocs build --strict
cd site && python3 -m http.server 8002

📊 Deployment-Status

Produktions-URL

  • Custom Domain: https://docs.karma.organic (nach Setup)
  • Pages.dev URL: https://solarlog-docs.pages.dev

Build-Status

  • Letzte Änderung: Automatisch bei Git Push
  • Build-Zeit: ~30 Sekunden
  • Deploy-Zeit: ~10 Sekunden

Features

✅ Automatische Deployments (Git Push) ✅ Instant Rollbacks ✅ Branch Previews ✅ Analytics (optional) ✅ Web Analytics (optional) ✅ Global CDN ✅ Kostenlos (Unlimited Requests)

🛠️ Troubleshooting

Build Failed

# Lokal testen
python3 -m mkdocs build --strict --verbose

# Dependencies prüfen
python3 -m pip list | grep mkdocs
  • Stelle sicher, dass site_url in mkdocs.yml korrekt ist
  • Bei Custom Domain: site_url: https://docs.karma.organic
  • Bei Pages.dev: site_url: https://solarlog-docs.pages.dev

404 Fehler

  • Prüfe build output directory: site in Cloudflare Pages
  • Prüfe dass mkdocs.yml im Root-Verzeichnis ist

💡 Best Practices

  1. Immer --strict verwenden beim Build
  2. Findet broken Links

  3. Erzwingt valide Markdown

  4. Site URL konfigurieren 

    # mkdocs.yml
site_url: https://docs.karma.organic

  5. Branch Previews nutzen

  6. Jeder Branch bekommt eigene Preview-URL

  7. Teste Änderungen vor Merge

  8. Analytics aktivieren (optional)

  9. Cloudflare Web Analytics
  10. Kostenlos, privacy-friendly

🎯 Nächste Schritte

  1. ✅ Statische Seiten generiert (site/ Ordner)
  2. ⏳ Push zu GitHub
  3. ⏳ Cloudflare Pages Projekt erstellen
  4. ⏳ Custom Domain konfigurieren
  5. ⏳ Frontend Links aktualisieren

Bereit für Deployment! 🚀