OSS/build_webstatic
SHA256
0
0
Fork 0
Code Activity
Files
main
build_webstatic/plans/00-produkt-webstatic.md
T
gc-dev-afjd eb098f9ff3 feat: Change license from MIT to Apache-2.0 
- Added LICENSE.md file with Apache License 2.0 text.
- Created NOTICE file for attribution of third-party components.
- Updated README.md to reflect the new license and included details about the Apache-2.0 license.
- Documented the license change in the diary entry for July 12, 2026.
- Updated installation instructions in getting-started.md to reflect per-user installation.
- Added reusable license header to all source files.
- Updated various documentation files to mention the new Apache-2.0 license.
- Changed legal mentions in example content to reflect the new license.
2026-07-12 19:29:20 +02:00

8.6 KiB
Raw Permalink Blame History

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: <title>, 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.
View Git Blame Copy Permalink