Architektur
easyWebsite ist ein Werkzeug-Ökosystem, mit dem aus Markdown-Dateien barrierefreie, statische Webseiten im KERN-UX- oder Bundes-Design entstehen. Diese Seite erklärt die Architekturentscheidungen und warum es zwei Nutzungsvarianten gibt.
Zwei Nutzungsvarianten
easyWebsite richtet sich an zwei unterschiedliche Zielgruppen mit grundlegend verschiedenen Anforderungen — und bietet deshalb zwei klar getrennte Varianten:
| Easy Mode | Developer Mode | |
|---|---|---|
| Zielgruppe | Redakteur:innen, Autor:innen | Entwickler:innen |
| Voraussetzung | Kein technisches Vorwissen nötig | Kenntnisse in Next.js und React |
| Anpassbarkeit | Eingeschränkt (CLI-Optionen) | Vollständig |
| Setup | CI/CD-Pipeline konfigurieren | Eigenes Next.js-Projekt |
Easy Mode
Wer Inhalte veröffentlichen möchte, ohne sich mit Code zu befassen, nutzt den Easy Mode. Hier schreibt man Markdown-Dateien, konfiguriert das Projekt über Umgebungsvariablen in der GitLab CI/CD-Pipeline — den Rest übernimmt die markdown-webbook CLI automatisch:
- Erstellt ein temporäres Next.js-Projekt aus einem internen Template
- Kopiert die Markdown-Inhalte hinein
- Generiert Konfigurationsdateien (
theme.config.tsx,next.config.mjs,_app.tsx,_document.tsx) - Führt den Next.js-Build aus
- Liefert statisches HTML
Autor:innen sehen zu keinem Zeitpunkt generierten Code. Dafür sind Anpassungen auf die verfügbaren CLI-Optionen beschränkt — eigene Komponenten oder abweichende Layouts sind nicht möglich.
- Tutorial: Erste Webseite erstellen
- Tutorial: Inhalte erstellen
- Beispielprojekt: markdown-zu-kern-ux-webseite
- CLI-Package: markdown-webbook
Developer Mode
Wer volle Kontrolle über Layout, Komponenten und Verhalten braucht, setzt ein eigenes Next.js-Projekt auf und bindet die easyWebsite-Packages direkt als npm-Abhängigkeiten ein:
@document-writing-tools/kernux-theme— Layout, Navigation, Suche, Feedback, MDX-Komponenten@document-writing-tools/kernux-react— Kern UX Design System React-Komponenten
Das eigene Projekt kann beliebig erweitert werden: zusätzliche Seiten, eigene React-Komponenten, angepasstes Styling. Im Gegenzug ist technisches Wissen über Next.js und React Voraussetzung.
- Tutorial: Developer Mode einrichten
- Beispielprojekt: gitlab-profile
- Beispielprojekt: opencode-tools-and-services-webseite
Technologie-Stack
easyWebsite baut auf folgenden Open-Source-Technologien auf:
| Technologie | Rolle |
|---|---|
| Next.js | React-Framework, SSG, Routing |
| React | UI-Bibliothek |
| KERN-UX | Design-System der öffentlichen Verwaltung |
| Tailwind CSS | Utility-first CSS-Framework |
| Flexsearch | Client-seitige Volltextsuche |
| Zod | Schema-Validierung |
Package-Registrierung
Alle Packages werden sowohl auf npm als auch in der GitLab Package Registry auf openCode veröffentlicht.
npm — keine zusätzliche Konfiguration nötig, direkt installierbar:
openCode GitLab Registry — erfordert einen Eintrag in der .npmrc: