# GitCover.WebStaticBuilder — Produktbeschreibung & Umsetzungsplan > Status: Implementierung (Phase 1–3 abgeschlossen, Build verifiziert, zwei reale Sites gebaut). Eigenständiges OSS-Static-Site-Tool der GitCover Commons. > Lizenz: Apache-2.0 (explizite Patentlizenz §3 + Retorsionsklausel gegen Patentklagen). Sprachen: C# / .NET 10 (keine Python-Abhängigkeiten). > Version: `1.0.0.0`. ## 1. Zweck `GitCover.WebStaticBuilder` (CLI-Befehl `webstatic`) ist ein schlanker, kompilierter Static-Site-Generator für mehrsprachige, SEO-optimierte, compliance-freundliche Websites. Er liest Markdown-Quellen mit YAML-Frontmatter, rendert sie pro Sprache zu statischem HTML, erzeugt Navigation, SEO-Kopf (OpenGraph/JSON-LD), Sitemap, robots.txt und einen client-seitigen Volltextindex (Pagefind) — ohne Server, Datenbank oder Build-Service. Das Tool ist die Verallgemeinerung des Builders, der die GCBoK-Website erzeugt, und soll es insbesondere **KMU-Anwendern** ermöglichen, eigene Websites nach derselben Funktionsweise zu erstellen. ## 2. Zielgruppe - **Primär:** KMU, die eine mehrsprachige, datenschutzfreundliche, revisionssichere Website/ Dokumentation betreiben wollen (kein JS-Framework, kein Tracking, statisch hostbar). - **Sekundär:** OSS-Projekte, Behörden, gemeinnützige Träger mit BoK-/Compliance-Anspruch. ## 3. Architektur & Technik - **C# / .NET 10**, kompilierte Konsolen-App (`OutputType Exe`), Ziel-Framework `net10.0`, Assembly `webstatic`. - **NuGet (alle MIT/BSD-2, lizenzkonform):** `Markdig` (BSD-2), `YamlDotNet` (MIT). Machine-Translation nutzt `System.Net.Http` (kein Extra-Paket). - **Kein Python.** Einziger externer Build-Schritt: `npx pagefind` (Node, best-effort, per Config abschaltbar). - Modulare `src/`-Struktur: `BuildConfig`, `Directories`, `Model`, `ContentLoader`, `MarkdownProcessor`, `SeoHelper`, `I18n`, `Builder`, `Translation/*`. ## 4. Funktionsumfang - Markdown + YAML-Frontmatter → statisches HTML pro Sprache (eigener Ordner je Sprache). - Automatische Navigation (`.md`-Reihenfolge via `order`/`section`), Sidebar-TOC, Prev/Next. - SEO: ``, Description, Canonical, OpenGraph, Twitter-Card, **JSON-LD**; `sitemap.xml`, `robots.txt`. - Mermaid-Diagramme (CDN, saubere einmalige Initialisierung), responsives Layout. - **Client-Suche:** Pagefind-Index im Post-Build (Mehrsprachigkeit via `<html lang>`). - **i18n:** UI-Chrome (Nav/Footer/ARIA/Sprachumschalter) mehrsprachig über `I18n.cs` + `{{ i18n.* }}`-Platzhalter. - **MT-Helfer:** `translate --check` meldet fehlende Übersetzungen; `translate --draft` erzeugt Entwürfe (nie auto-überschreiben). - **Umgebungen:** deklarativ in Config, wählbar via `--env`. ## 5. Mehrsprachigkeit - Inhalte: pro Sprache eigene Datei (`<basis>.<lang>.md`), Fallback-Logik. - UI-Strings: portiertes `i18n.py`-Wörterbuch nach `I18n.cs` (de/en/vi), zur Laufzeit pro Sprache injiziert. - Kultur-korrekte Datums-/Zahlformate über `System.Globalization` (vorbereitet). - Optional: MT-Provider (Azure/DeepL) erzeugt **Entwürfe** für fehlende Inhaltsübersetzungen (klar markiert, separater Ordner `.translation-drafts/`). ## 6. Umgebungen (Arbeitsumgebung / Staging / Public Deployment) | Umgebung | `--env` | baseUrl (Beispiel) | cdn | Zweck / Ort | |---|---|---|---|---| | **Arbeitsumgebung** | `development` (`--preview`/`--work`/`--review` sind Aliase) | `http://localhost:8000` | `/assets` | Lokale Entwicklung; Build→lokales `dist/`, Vorschau via `serve` | | **Staging** | `staging` | `https://gcbok.gitcover.org` | `https://gitcover.org/assets` | Abnahme (brx5 `/var/www/gcbok.gitcover.org`) | | **Public Deployment** | `deploy` | `https://gcbok.org` | `https://gitcover.org/assets` | Production (manueller Upload WebFTP) | Hinweis: `work`/`preview`/`review` werden im Code alle auf `development` gefaltet. Die Default-Environments in `BuildConfig.Defaults()` sind `development`/`staging`/`deploy`. ## 7. CLI-Referenz ``` webstatic build --env <development|staging|deploy> [--content DIR] [--templates DIR] [--assets DIR] [--output DIR] [--base-url URL] [--cdn PATH] [--langs de,en,vi] [--default-lang de] [--config FILE] [--root DIR] [--verbose] [--dry-run] webstatic translate --check # fehlende Übersetzungen melden webstatic translate --draft # Entwürfe erzeugen (MT, API-Key nötig) webstatic init <sitename> # KMU-Onboarding: Site scaffolden webstatic serve [--port 8000] # lokale Vorschau (.NET HttpListener) webstatic status # rendert der Site README.md im Terminal ``` Aliase `--preview`/`--work`/`--review` = `development`, `--staging` = `staging`, `--deploy` = `deploy`. Subcommands: `build`, `serve`, `init`, `translate`, `status`. ## 8. Konfiguration (`webstatic.json`) - `site` (name/title/description je Sprache), `default_language`, `languages` (name/og_locale/href_lang/label), `paths` (content/templates/assets/output/legal/i18n), `glossary_section` + `glossary.href/label`, `pagefind` (bool), `translator` (provider/key_env/endpoint/region), `environments` (`development`/`staging`/`deploy` mit base_url/cdn). - Priorität: CLI-Flags > `webstatic.json` > eingebaute Defaults. ## 9. Installation für KMU (`install.sh`) - Bash-Skript (kein Python): prüft .NET 10, `dotnet build -c Release`. - **Default (per-user):** kopiert nach `~/.local/share/GitCover/webstatic`, Launcher `~/.local/bin/webstatic`; Updates via `webstatic update`. - **Optional (System, root):** `WEBSTATIC_INSTALL_DIR=/opt/GitCover/webstatic WEBSTATIC_BIN_DIR=/usr/local/bin ./install.sh` kopiert nach `/opt/GitCover/webstatic`, Symlink `webstatic`→App nach `/usr/local/bin`. - Idempotent; meldet Voraussetzungen. ## 10. Onboarding-Flow für KMU - `webstatic init <sitename>` scaffolder: kopiert `webstatic.example/` (content/templates/assets + Config), fragt Sprachen/Site-Titel. - `webstatic serve` (lokale Vorschau) und `webstatic build --env staging` als Kern. - Review-Gate/Konzept (Assistent, Freigabe) wird separat finalisiert. ## 11. Repository-Struktur (Ziel) ``` build_webstatic/ plans/ # dieser Plan + Folgepläne docs/ # Anleitungen (KMU, Admin) diary/ # Entwicklungs-Tagebuch / Changelog src/ # C#-Quellcode (GitCover.WebStaticBuilder) tests/ # (künftig) Unit/Integrationstests webstatic.example/ # Vorlage-Site für KMU install.sh README.md LICENSE (Apache-2.0) NOTICE AGENTS.md MEMORY.md SKILLS.md ``` ## 12. Lizenz & Compliance - Code: **Apache-2.0** (`LICENSE.md`, `NOTICE`). Bietet im Gegensatz zu MIT eine **explizite Patentlizenz** (§3) sowie eine **Retorsionsklausel** (Patentlizenz erlischt bei Patentklage über die Software) — bewusst gewählt, weil der Builder an vielen Stellen patentrelevante Logik implementiert. Kompatibel mit den NuGet-Deps `Markdig` (BSD-2) und `YamlDotNet` (MIT); deren Lizenzen bleiben in `NOTICE` erhalten. GPLv2-inkompatibel, GPLv3+ ok. - Inhalte der GCBoK-Site: separat (angestrebt CC BY-SA 4.0) — betrifft das Tool nicht. ## 13. Umsetzungsphasen - **Phase 0 — Dev-Setup:** `build_webstatic` auf `/mnt/brx5/work/OSS/build_webstatic` (kopiert aus `www/build`, Python/`build.csx` entfernt, Verzeichnisstruktur plans/docs/diary/src/tests). - **Phase 1 — Refactor (DONE):** Umbenennung `GitCover.WebStaticBuilder`; Python entfernt; Config/Umgebungsmodell; i18n (`I18n.cs` + Platzhalter); MT-Helfer; Pagefind; `webstatic.example`; `install.sh`; Docs/LIZENZ. Build & Verify auf Beispielsite ✓. - **Phase 2 — Install & Verify (DONE):** Per-user Betatester-Install unter `~/.local/share/GitCover/webstatic` (Launcher `~/.local/bin/webstatic`) ist die **aktive** Installation; optionale System-Installation unter `/opt/GitCover/webstatic` (root). `webstatic update` aktualisiert den per-user-Clone (stash/pull/merge/rebuild, Hermes-Konzept). Standalone-Smoke-Test ✓. - **Phase 3 — Website-Repo (DONE):** GCBoK-Repo und GCC-Repo nutzen ausschließlich die `webstatic`-CLI (Python/`www/build*` entfernt). gcc.gitcover.org am 2026-07-12 migriert (Multi-Page, `*.de.md` autoritativ, Banner aus gcbok, Eyebrow+Titel als Seiten-Header auf allen Seiten). `pagefind` pro Site per `pagefind: false` abschaltbar. - **Phase 4 — Onboarding:** `init`/`serve`/`build` als KMU-Flow (Konzept finalisieren). - **Phase 5 — Abschluss:** Zusammenfassung; Commit/Signierung nur auf Wunsch. ## 14. Offen / Risiken - **Review-Umgebung:** Konzept (Host/Subdomain/Freigabe) noch offen. - **MT-Sicherheit:** Entwürfe nur als Draft, nie auto-übernommen. - **Rückwärtskompat GCBoK:** Config-Defaults spiegeln GCBoK-Struktur. - **Portabilität:** `/opt` maschinenspezifisch → `WEBSTATIC_BUILDER` + `install.sh` dokumentiert.