Build-Pipeline#

Diese Seite erklärt, was passiert, wenn die markdown-webbook CLI aus Markdown-Dateien eine statische Webseite erzeugt.

Überblick#

Markdown-Dateien → Preprocessing → Konfigurationsgenerierung → Next.js-Build → Statisches HTML

Der gesamte Prozess läuft in einem temporären Verzeichnis ab. Die CLI kopiert ein internes Next.js-Template, fügt die Inhalte ein, generiert Konfigurationsdateien und führt den Next.js-Build aus.

Schritt für Schritt#

1. Temporäres Verzeichnis erstellen#

Die CLI erstellt ein temporäres Verzeichnis (oder nutzt --build-directory, falls angegeben) und kopiert das interne Next.js-Template dorthin. Dieses Template enthält die Grundstruktur eines Next.js-Projekts mit allen notwendigen Abhängigkeiten.

2. Abhängigkeiten installieren#

Im temporären Verzeichnis wird npm install ausgeführt. Die Abhängigkeiten (@document-writing-tools/kernux-theme, React, Next.js etc.) sind im Template bereits deklariert.

3. Preprocessing (walkAndCopy)#

Die CLI durchläuft rekursiv das Input-Verzeichnis und kopiert Dateien in das pages-Verzeichnis des Templates. Dabei passieren mehrere Transformationen:

4. YAML-Dateien kopieren#

Die Glossar- und Abkürzungsdateien werden kopiert:

• Einzelsprache: abbreviations.yaml aus dem Root (empfohlen)
• Mehrsprachig: {locale}/abbreviations.yaml pro Sprache

glossar.yaml und abkuerzungen.yaml werden aus Kompatibilitätsgründen noch unterstützt, sollten aber nicht mehr genutzt werden.

5. Konfigurationsdateien generieren#

Die CLI erzeugt vier Dateien im temporären Verzeichnis, basierend auf den übergebenen CLI-Parametern:

theme.config.tsx — Exportiert ein KernuxThemeConfig-Objekt, befüllt aus den übergebenen CLI-Parametern. Das Objekt wird in _app.tsx als themeConfig-Prop an die Layout-Komponente übergeben.

next.config.mjs — Next.js-Konfiguration mit withMarkdownWebBook-Wrapper, i18n-Einstellungen (falls Mehrsprachigkeit), Bildoptimierung, statischem Export.

_app.tsx — Bindet die Layout-Komponente ein und übergibt ihr themeConfig sowie die pageMap als Props. Importiert außerdem das CSS-Theme.

_document.tsx — HTML-Dokument mit Sprach-Attribut, Analytics-Scripts (Umami/Plausible, falls konfiguriert), Locale-Erkennung bei Mehrsprachigkeit.

6. Glossar-Seite generieren#

Falls glossar.yaml oder abbreviations.yaml vorhanden sind, wird eine glossar.mdx-Seite generiert, die die Glossar-Komponente mit den Daten rendert. Bei Mehrsprachigkeit wird pro Locale eine eigene Glossar-Seite erstellt.

7. Self-Assessment verarbeiten (optional)#

Falls --selfassessment aktiviert ist:

• Alle Markdown-Dateien werden nach <!---Self Assessment: ... ---> Kommentarblöcken durchsucht
• Gefundene Fragen werden zu questions.json extrahiert
• Eine self-assessment.mdx-Seite wird generiert

8. Next.js-Build#

next build wird im temporären Verzeichnis ausgeführt. Dabei passiert:

• withMarkdownWebBook generiert die PageMap (Navigation) und Suchdaten
• MDX-Dateien werden kompiliert (mit Remark-Plugins für Abkürzungen, etc.)
• Statischer HTML-Export wird erzeugt

9. Ausgabe kopieren#

Das generierte out-Verzeichnis wird in das angegebene Output-Verzeichnis kopiert.

Watch-Modus#

Im Watch-Modus (--watch) wird statt next build ein next dev-Server gestartet. Dateiänderungen im Input-Ordner werden automatisch in das temporäre Verzeichnis synchronisiert, und Next.js aktualisiert die Vorschau.

Warum ein temporäres Verzeichnis?#

Der Ansatz hat einen klaren Grund: Autor:innen im Easy Mode sollen keinen Code sehen. Das temporäre Verzeichnis enthält das vollständige Next.js-Projekt mit allen generierten Konfigurationsdateien, Abhängigkeiten und Build-Artefakten — aber das bleibt alles unsichtbar. Im Quell-Repository liegen nur Markdown-Dateien und Assets.