Zuletzt aktualisiert:

Tech-Stack für die User-Doku (Endnutzer-Hilfe) — Tiefenrecherche

Für: Dennis (Silverscale Family Hub) · Stand: 10.06.2026 · Datenbasis: bestehender docs/build.py-Generator, docs/content/recherchen/doku-hosting.md, app/frontend/src/app.css (Design-Tokens), Webrecherche zum 2026-Stand der SSGs.

Es geht nicht um die bestehende technische Dev-Doku, sondern um eine nutzerfreundliche Hilfe für die Familie (Dennis + Jaqueline, nicht-technisch), abrufbar in der iOS-App (integrierte Hilfe) und am MacBook (Referenz).

1. Kurz-Fazit / Empfehlung

Den bestehenden docs/build.py-Generator ausbauen — NICHT ein SSG adoptieren.

Begründung in 4 Sätzen: Der Repo-eigene Generator ist bereits genau das, was hier gebraucht wird — Markdown → statisches HTML, maritime OKLCH-Tokens, Dark Mode, clientseitige Volltextsuche (search-index.json + Vanilla-JS), Bilder über img/-Ordner, Tabellen, interne/externe Links — und das mit null npm-Dependencies (nur stdlib + vendored python-markdown), was auf dem VPS und für einen Ein-Personen-Self-Host der schlankste denkbare Footprint ist. Jeder etablierte Stack (Starlight, VitePress, MkDocs Material, Nextra) würde eine node/Python-Toolchain plus 100–400 Build-Dependencies einführen, deren OKLCH-Theming-Tiefe und Markenkonsistenz wir mühsam nachbauen müssten — während wir die App-Tokens heute schon 1:1 tragen. Die zwei realen Lücken (echte „verwandte Themen" und ein App-taugliches Hilfe-Erlebnis) sind kleine, gezielte Erweiterungen am Generator, kein Grund für eine Migration. Kurz: Der Generator ist „gut genug + am schlanksten" — die richtige Antwort ist ausbauen, nicht ersetzen.

Verworfen, falls jemand fragt: Ein SSG wäre erst dann gerechtfertigt, wenn die Doku auf Dutzende Mitwirkende, versionierte API-Referenzen oder i18n-Mehrsprachigkeit wachsen würde. Nichts davon trifft auf eine 2-Personen-Familienhilfe zu.

2. In einfachen Worten

Wir haben für das Doku-Archiv längst einen eigenen kleinen „Doku-Backofen" gebaut (docs/build.py): vorne Markdown-Text rein, hinten fertige Webseiten im Look der App raus — inklusive Suchfeld, Hell/Dunkel und Bildern. Die Frage ist: bauen wir die Familien-Hilfe in diesen vorhandenen Ofen, oder kaufen wir uns einen fabrikneuen, großen Profi-Ofen (eines der bekannten Doku-Werkzeuge)?

Antwort: unser Ofen reicht. Die großen Werkzeuge können viel mehr, als zwei Leute je brauchen, bringen dafür aber einen Berg an Zusatzteilen mit, die gewartet werden wollen, und unser App-Aussehen müssten wir denen erst wieder beibringen. Unser Ofen spricht schon perfekt Silverscale-Design. Wir backen also die Familien-Hilfe damit und schrauben nur zwei kleine Dinge an: am Ende jeder Hilfeseite „Das könnte dich auch interessieren"- Links, und einen sauberen Weg, wie die iPhone-App eine Hilfeseite anzeigt.

3. Vergleichstabelle der Kandidaten

Bewertung: ++ stark · + ok · ~ Einschränkung · − schwach. Alle Aussagen Stand 2026-06-10.

Kriterium build.py (eigen, ausbauen) Astro Starlight VitePress MkDocs Material Nextra
Markdown-first ++ reines MD, LLM pflegt trivial ++ MD/MDX ++ MD (+ Vue in MD) ++ MD ~ MD/MDX (React)
Schlankheit / Dependencies ++ 0 npm, stdlib + vendored md − node + Astro-Toolchain − node + Vite/Vue ~ Python + pip-Stack − node + Next.js
Self-Host-Footprint VPS ++ schon live (nginx-Container, Bind-Mount) + statischer Export + statischer Export + statischer Export ~ 200–400 KB JS/Seite
Mobile-first + vorhanden, ausbaufähig ++ exzellent o.o.t.b. + gut ++ exzellent + gut
App-Embed (offline/Bundle) ++ wir besitzen jedes Byte ~ Pagefind braucht http(s)-Kontext ~ search braucht Server ~ search-Setup ~ JS-lastig
Volltextsuche o.o.t.b. + eigen (search-index.json + JS) ++ Pagefind eingebaut + lokale Suche ++ eingebaut + Flexsearch
OKLCH-Token-Theming ++ Tokens schon 1:1 aus app.css + CSS-Vars override (eigene Skala) + CSS-Vars ~ Farb-System eigenwillig + CSS-Vars
Related / Cross-Links ~ heute nur manuell + prev/next + manuell + manuell + manuell + manuell
Bilder / Screenshots ++ img/-Ordner kopiert ++ Assets-Pipeline ++ ++ ++
i18n (Doku = Deutsch) ++ irrelevant, einsprachig ok ++ (nicht gebraucht) + + +
Wartung (1 Person) ++ ein Skript, kein Lockfile ~ npm-Updates, Astro-Majors ~ npm-Updates ~ Maintenance-Mode seit 11/2025 ~ Next-Majors
LLM pflegt Inhalte ++ pure .md, kein Frontmatter-Zwang + .md + Frontmatter + + ~ MDX/JSX-Fallen
Migration docs/content/ ++ null (gleiche Struktur) ~ Frontmatter/Slugs umbauen ~ ~ ~

Lesart: build.py gewinnt überall dort, wo es für dieses Projekt zählt (Schlankheit, schon-live, Token-Konsistenz, App-Kontrolle, LLM-Pflege, Null-Migration). Die SSGs gewinnen nur bei Dingen, die wir nicht brauchen (Out-of-the-box-Politur für große Teams, MDX-Komponenten, i18n-Workflows). MkDocs Material ist seit dem 05.11.2025 offiziell im Maintenance-Mode (9.7.0 vom 11.11.2025 war das letzte Feature-Release; nur noch kritische Fixes/Security bis ~Nov 2026) — als „neuer" Stack 2026 disqualifiziert. Starlight wäre der stärkste Alternativkandidat (leichtester JS-Output, Pagefind, sauberes CSS-Var-Theming), scheitert hier aber an der App-Embed- Reibung (Pagefind, siehe §6) und dem Toolchain-/Migrations-Mehraufwand ohne echten Gewinn.

4. Tiefe Begründung der Empfehlung

4.1 Was build.py heute schon kann (gemessen, nicht vermutet)

Damit deckt der Generator fast die gesamte Anforderungsliste schon ab: interne + externe Links ✓, Tabellen ✓, Bilder ✓, Formatierung ✓, Volltextsuche ✓, mobile ✓, desktop ✓, Token-Theming ✓. Offen sind nur „verwandte Themen" (heute nur manuell verlinkbar) und die App-Integration.

4.2 Warum ein SSG hier mehr Schaden als Nutzen bringt

  1. Dependency-Footprint. Der Generator hat null npm-Pakete. Starlight/VitePress/ Nextra ziehen eine node-Toolchain + hunderte transitive Deps + Lockfile ins Repo, die ein Ein-Personen-Self-Host dauerhaft updaten/patchen muss. MkDocs Material zieht einen pip-Stack — und ist obendrein im Maintenance-Mode.
  2. Theming-Rückschritt. Wir tragen die App-Tokens aus app.css heute direkt. Bei einem SSG müssten wir dessen eigene Farb-/Spacing-Skala (--color-accent-*, --color-gray-* bei Starlight; eigene Systeme bei den anderen) auf unsere OKLCH- Tokens zurückmappen — Mehrarbeit, um den Status quo wiederherzustellen.
  3. Zwei Doku-Generatoren. Die Dev-Doku läuft bereits über build.py. Ein SSG nur für die User-Doku spaltet das Archiv in zwei Build-Systeme, zwei Looks-Quellen, zwei Deploy-Wege — das Gegenteil von „schlank, nichts Wildes".
  4. LLM-Pflegbarkeit. Reine .md-Dateien ohne Frontmatter-Pflicht/MDX/JSX sind für einen Agenten am robustesten. MDX/JSX (Nextra) sind eine Fehlerquelle.
  5. App-Kontrolle. Für die In-App-Hilfe (§6) ist es Gold wert, jedes Byte des Outputs zu besitzen — die HTML-Struktur, die Suche, die Header. Ein SSG-Output ist eine Blackbox, die wir für Bundling/Deep-Links erst wieder aufbrechen müssten.

4.3 Der ehrliche Trade-off

Was wir mit „ausbauen" aufgeben: das kostenlose Mobile-Polish und die Pagefind-Suche, die Starlight out-of-the-box liefert. Aber unser Mobile-Layout ist bereits brauchbar, unsere Suche funktioniert, und der Reim ist: Wir investieren ~1 Tag in zwei gezielte Erweiterungen statt mehrere Tage in Migration + Re-Theming + Toolchain-Pflege, die uns unterm Strich denselben Funktionsumfang in einer fremderen, schwereren Hülle gäben.

5. Geplante Ausbau-Punkte am Generator (Feature-Set, nicht mehr)

  1. „Verwandte Themen" (related/cross-links). Pro Hilfeseite ein optionaler related:-Block. Schlankste Variante: ein leichtgewichtiger Frontmatter-Header (YAML-Frontmatter zwischen ---), aus dem build.py einen „Das könnte dich auch interessieren"-Footer rendert (Titel + Slug-Auflösung über die schon vorhandene Doc-Liste). Alternativ ohne Frontmatter: eine Konvention <!-- related: scan, plan -->. Frontmatter ist sauberer und LLM-freundlich → empfohlen.
  2. Hilfe-spezifische Slugs. Stabile, sprechende URLs je Kernfeature (user/scan.html, user/plan.html, user/tagebuch.html …) als Deep-Link-Ziele für die App-?-Buttons. Liegt heute schon implizit am Dateinamen — nur konsequent benennen + dokumentieren.
  3. Mobile-Politur der user/-Kategorie. Größere Touch-Ziele, Hilfe-freundliche Typo (kürzere Zeilen, mehr Luft), evtl. eine eigene „Hilfe"-Hero-Variante. Reines CSS in docs/assets/docs.css, kein Strukturumbau.
  4. (Optional) Such-Anchor-Tiefe. Heute indexiert die Suche pro Dokument; für eine Hilfe lohnt evtl. Abschnitts-genaues Springen (#anker) in den Treffern. Klein, optional.

6. App-Integrations-Konzept (zentral)

Die iOS-App ist nativer SwiftUI-Reimplement (app/ios-native/). Die Hilfe wird darin über ?-Buttons / einen Hilfe-Tab konsumiert. Drei Architektur-Optionen — Empfehlung zuerst:

Option A (empfohlen): Remote von silverscale-docs.dennisfisch.de, In-App-WKWebView-Sheet

Option B (Offline-Fallback, nur wenn gewünscht): gebündelte statische Site im App-Bundle

Empfehlung: Option A jetzt (remote + In-App-WKWebView-Sheet, Deep-Links über stabile Slugs). Option B später als optionaler Offline-Layer, falls Dennis Offline- Hilfe priorisiert — der eigene Single-File-Suchindex macht das einfacher als jeder Pagefind-SSG es täte (zusätzliches Argument für „ausbauen").

7. Design-Token-Fluss (app.css → Doku)

Quelle der Wahrheit: app/frontend/src/app.css (OKLCH-Skala --ss-*: --ss-aqua-*, --ss-azure-*, --ss-ink-*, --ss-bg/-surface/-hairline, Gradienten --ss-grad-*, Typo --ss-font-display = Fraunces / --ss-font = Inter Tight, Dark-Mode-Block unter :root[data-theme="dark"]).

Heute liegen die Tokens in docs/assets/docs.css als Kopie. Damit die Doku die Markenkonsistenz nicht driftet, gibt es zwei Wege:

  1. Build-Sync (empfohlen, schlank): build.py extrahiert beim Build die --ss-*- Token-Blöcke aus app/frontend/src/app.css (Light + Dark) und injiziert sie als :root/:root[data-theme="dark"]-Block in docs/assets/docs.css (oder in einen generierten tokens.css-Teil). Ein Regex/Block-Parser auf die :root { … }-Bereiche genügt (gleiche Technik wie die schon vorhandenen Regex-Helfer im Generator). Vorteil: eine einzige Token-Quelle, automatisch konsistent, kein Hand-Nachpflegen.
  2. Manuell synchron halten (Status quo): funktioniert, driftet aber über die Zeit.

→ Für „nichts Wildes" + Markenkonsistenz ist Build-Sync der beste Kompromiss: kleine Erweiterung im Generator, danach trägt die Doku automatisch immer den aktuellen App-Look. (Bei einem fremden SSG wäre genau dieser Fluss der Mehraufwand, den wir uns sparen.)

8. Migrations-/Umsetzungsskizze, Risiken, Aufwand

Schritte (alle am bestehenden Generator): 1. docs/content/user/ mit echten Hilfe-.md-Seiten füllen (Tagebuch, Wochenplan, Vorrat, Scannen, Aktivitäten, Einkaufsliste, …) — reine Markdown-Dateien, eine pro Kernfeature, stabile Slugs (§5.2). 2. related:-Frontmatter + Footer-Rendering in build.py ergänzen (§5.1). 3. Token-Build-Sync app.css → docs.css in build.py einbauen (§7.1). 4. Mobile-/Hilfe-Politur in docs/assets/docs.css (§5.3). 5. App-Seite: openHelp(slug) → In-App-WKWebView-Sheet auf https://silverscale-docs.dennisfisch.de/user/<slug>.html; ?-Buttons in den Kernscreens verdrahten (MacClaude-Revier, app/ios-native/). 6. Deploy wie gehabt: python3 docs/build.py → docker restart silverscale-docs (site/ nie löschen). 7. (Optional, später) Offline-Bundle-Variante (§6 Option B).

Risiken / Stolperfallen: - Bind-Mount: docs/site/ niemals rmtreeen (Generator macht das korrekt — bei Erweiterungen beibehalten). - file://-Falle: Falls je Option B gebaut wird, relative Links erzwingen und Suche gegen file:// testen (WebKit-Subresource-Limit; unser Single-File-Index ist hier der Vorteil). - Token-Parser-Brüchigkeit: Der app.css-Block-Extraktor muss tolerant gegen Kommentare/zusätzliche :root-Blöcke sein (Light + Dark sauber trennen). - Revier-Trennung: Doku/build.py = StratoClaude; ?-Buttons/WKWebView-Sheet = MacClaude (app/ios-native/). Dieselbe Datei nie von beiden committen.

Aufwandsschätzung (grob): - Generator-Ausbau (related + Token-Sync + Mobile-CSS): ~0,5–1 Tag. - Hilfe-Inhalte schreiben: laufend, inhaltsgetrieben (nicht Stack-Aufwand). - App-?-Buttons + WKWebView-Sheet (Option A): ~0,5 Tag auf der Native-Seite. - Offline-Bundle (Option B), optional: +1–1,5 Tage inkl. file://-Tests.

9. Quellen (Abruf 2026-06-10)