[[Uebersicht|← Zurück zur Homepage]] # Pflichtenheft: MkDocs-Material-Migration > [!info] Kurzfassung > Umzug der öffentlichen Doku von **Obsidian Publish** auf eine mit **MkDocs Material** generierte, statische Website. Build & Deploy vollautomatisch über **GitHub Actions → GitHub Pages**. Interne/sensible Bereiche werden bei der Migration **ausgefiltert**. Grundlage: [[01 Machbarkeits-Check MkDocs-Migration]] (Machbarkeit hoch, geringes Risiko). ## 1. Ziel Die Vault-Dokumentation soll als schnelle, kostenlose, SEO-starke statische Website unter `doku.monis-elektro-base.com` laufen — mit voller Kontrolle über Navigation, Meta-Tags, `sitemap.xml` und `robots.txt`. Obsidian Publish (8 $/Monat) wird abgelöst. ## 2. Ausgangslage - Aktuell: Obsidian Publish (JS-App), 144 Markdown-Dateien, 563 Wikilinks (0 mit Ordnerpfad), 40 Attachments. - Details & Bewertung: siehe [[01 Machbarkeits-Check MkDocs-Migration]]. ## 3. Rahmenbedingungen & Grundentscheidungen | # | Entscheidung | Festlegung | |---|---|---| | E1 | Static Site Generator | MkDocs + Theme **Material for MkDocs** | | E2 | Build & Deploy | **GitHub Actions** (automatisch bei Push) → **GitHub Pages** | | E3 | Hosting | GitHub Pages (NICHT Cloudflare Pages – laut Historie gescheitert) | | E4 | DNS/Proxy | Cloudflare bleibt davor (CNAME auf GitHub Pages) | | E5 | Umfang | Interne/sensible Bereiche **ausfiltern** (nicht veröffentlichen) | | E6 | Quelle | Bestehendes GitHub-Repo `moni-elektro-base` | ## 4. Funktionale Anforderungen ### 4.1 Grundsetup - [ ] `mkdocs.yml` anlegen: `site_name`, `site_url`, `site_description`, `theme: material` - [ ] Material-Features: Volltextsuche, Dark-/Light-Mode-Umschalter, responsive Navigation, „Zurück nach oben" - [ ] `requirements.txt` mit MkDocs + Material + Plugins (für reproduzierbaren Build) ### 4.2 Inhalts-Konvertierung (automatisiert via Plugins) - [ ] `[[Wikilinks]]` (563×) → echte Links: Plugin `mkdocs-roamlinks` oder `mkdocs-ezlinks` (nutzt die reine-Dateinamen-Konvention) - [ ] Embeds `![[Bild]]` (34×) → Bild-Einbindung, optional `mkdocs-glightbox` (Lightbox) - [ ] Callouts `> [!info]` (8×) → Material-Admonitions: Plugin `mkdocs-callouts` - [ ] **Dataview-Block (1×)** → manuell durch statischen Inhalt/Tabelle ersetzen (Dataview existiert in MkDocs nicht) - [ ] Attachments/Bilder-Ordner in den Build übernehmen ### 4.3 Ausschluss interner Bereiche (E5) - [ ] Ausschluss konfigurieren via `mkdocs-exclude` bzw. `.pages`-Dateien (`mkdocs-awesome-pages-plugin`) - [ ] **Ausschluss-Kandidaten (final zu bestätigen):** - `90 Inbox/` (unfertige Notizen) - `Templates/` - `40 Projekte/NoteMyVoice/memory/` und weitere `memory/`-Inhalte - `50 Wissen/Wie wir mit Claude arbeiten/` (interne Claude-Workflows) – *prüfen, ob öffentlich gewünscht* - ggf. weitere projektinterne Prompts/Setups ### 4.4 Navigation - [ ] `mkdocs-awesome-pages-plugin` nutzen → Reihenfolge über die vorhandenen `01/02`-Nummernpräfixe - [ ] Startseite festlegen (`Uebersicht` als `index`) - [ ] Entscheidung: manuelles `Inhaltsverzeichnis` + Auto-TOC-Pre-Commit-Hook wird durch Material-Navigation überflüssig → Hook deaktivieren/entfernen ### 4.5 SEO - [ ] Meta-Description pro Seite (Frontmatter oder erste Zeilen) - [ ] `sitemap.xml` (Material generiert automatisch) + `robots.txt` - [ ] Canonical-URLs korrekt (`site_url` gesetzt) - [ ] Google Analytics einbinden (**Tag-ID steht noch aus** – siehe offene Punkte) - [ ] Open-Graph/Social-Cards (Material `social`-Plugin, optional) ### 4.6 Deploy-Pipeline (GitHub Actions) - [ ] Workflow `.github/workflows/` : bei Push auf `main` → MkDocs bauen → auf `gh-pages` deployen (`mkdocs gh-deploy` bzw. Actions-Workflow) - [ ] GitHub Pages im Repo auf Branch `gh-pages` aktivieren - [ ] Build-Fehler brechen den Deploy ab (kein kaputter Stand live) ### 4.7 Domain-Umzug - [ ] `CNAME`-Datei mit `doku.monis-elektro-base.com` im Build - [ ] Custom Domain in GitHub Pages eintragen (HTTPS erzwingen) - [ ] Cloudflare: CNAME `doku` von Obsidian Publish → GitHub Pages umstellen - [ ] Umlaut-/Sonderzeichen-Slugs prüfen (`Datenschutzerklärung`, `Design – PDF-Extraktion`) ### 4.8 Parallelbetrieb & Umschaltung - [ ] MkDocs zuerst unter Test-URL (GitHub-Pages-Standarddomain) aufbauen und prüfen - [ ] Obsidian Publish parallel weiterlaufen lassen bis zur finalen Umschaltung - [ ] Erst nach erfolgreicher Prüfung Domain umhängen, dann Obsidian Publish kündigen ## 5. Nicht-funktionale Anforderungen - Responsive (Desktop + Smartphone), Dark-/Light-Mode - Schnelle Ladezeit (statisches HTML) - Eingebaute Volltextsuche - Deutsch als Sprache (`language: de`) - Einheitliches Erscheinungsbild (Material-Theme, ggf. Farbschema) ## 6. Abnahmekriterien - [ ] Alle öffentlichen Seiten sind erreichbar, interne Bereiche sind **nicht** enthalten - [ ] Interne Links (563) funktionieren, keine Broken Links (Prüfung via `mkdocs build --strict`) - [ ] Bilder/Embeds werden angezeigt - [ ] `sitemap.xml`/`robots.txt` vorhanden und korrekt - [ ] Push auf `main` deployt automatisch die aktualisierte Seite - [ ] `doku.monis-elektro-base.com` zeigt die neue Seite mit gültigem HTTPS - [ ] Google-Indexierung funktioniert (Search Console, `site:`-Test) ## 7. Risiken & Gegenmaßnahmen | Risiko | Gegenmaßnahme | |---|---| | Broken Links durch Umlaut-Slugs | `--strict`-Build + Link-Check vor Umschaltung | | Falsch ausgefilterte Seiten (zu viel/zu wenig) | Ausschlussliste vorab bestätigen (4.3) | | Deploy bricht Live-Seite | Parallelbetrieb + Deploy nur bei fehlerfreiem Build | | Cloudflare-Pages-Wiederholung | bewusst GitHub Pages (E3) | ## 8. Rollback Bis zur Kündigung von Obsidian Publish jederzeit möglich: Cloudflare-CNAME zurück auf Obsidian Publish zeigen lassen — die alte Site ist sofort wieder live. ## 9. Offene Punkte / Entscheidungen - [ ] **Google Analytics Tag-ID** beschaffen/eintragen - [ ] Ausschlussliste (4.3) final bestätigen - [ ] Farbschema/Branding für Material festlegen (Standard oder eigenes) - [ ] Umgang mit `Inhaltsverzeichnis` + Auto-TOC-Hook entscheiden ## 10. Grobe Phasen / Aufwand | Phase | Inhalt | Aufwand | |---|---|---| | 1 | Grundsetup `mkdocs.yml` + Plugins + lokaler/Test-Build | 1–2 h | | 2 | Konvertierung prüfen (Links, Embeds, Callouts, Dataview) | 1–2 h | | 3 | Ausschluss interner Bereiche + Navigation | 1 h | | 4 | GitHub-Actions-Pipeline + GitHub Pages | 1 h | | 5 | SEO + Analytics + Feinschliff | 1 h | | 6 | Domain-Umzug + Abnahme + Obsidian Publish kündigen | 1 h | **Gesamt:** ca. ein halber bis ganzer Arbeitstag. --- **Status:** Geplant **Version:** 1.0 **Zuletzt aktualisiert:** 2026-07-12 15:29 Uhr ### Änderungshistorie | Version | Datum | Uhrzeit | Änderung | |---|---|---|---| | 1.0 | 2026-07-12 | 15:29 | Erstfassung – Build via GitHub Actions, interne Bereiche ausfiltern | --- [[Impressum|Impressum]] | [[Datenschutzerklärung|Datenschutz]]