SHA256
gc-dev-afjd
ca34a5f866
- Program.cs: PrintVersion() vergleicht Assembly-Version mit README.md (Block-Quote '> **Version: X.Y.Z**') und warnt bei Mismatch. Remote-Check via 'git ls-remote origin HEAD' vergleicht lokalen mit remote Commit-Hash; Hinweis 'UPDATE AVAILABLE' bei Differenz. Copy-Installationen (kein .git) erhalten Hinweis auf ./install.sh. - README.md: Versions-Block-Quote unter dem Titel (kanonisch), Update-Check-Doku, drei synchrone Versionsquellen dokumentiert. - AGENTS.md: Versions-Definition als Definition of Done für Releases (README + csproj + Assembly müssen synchron sein).
146 lines
5.2 KiB
Markdown
146 lines
5.2 KiB
Markdown
# GCBoK.WebStaticBuilder
|
|
|
|
> **Version: 1.0.0** — Diese Versionsnummer steht in `README.md` (kanonisch),
|
|
> in `GCBoK.WebStaticBuilder.csproj` (`<Version>`) und wird von `webstatic --version`
|
|
> ausgegeben. Alle drei Quellen müssen synchron gehalten werden.
|
|
|
|
Eigenständiger, quelloffener **Static-Site-Generator** der GitCover Commons für
|
|
mehrsprachige, SEO-optimierte, compliance-freundliche Websites. Ersetzt den
|
|
früheren C#-Builderskript der GCBoK-Website durch ein generisches, für KMU
|
|
einsetzbares Werkzeug.
|
|
|
|
- **Sprache:** C# / .NET 10 (kompilierte Konsole)
|
|
- **Lizenz:** MIT (siehe `LICENSE` für Third-Party-Dependency-Lizenzen)
|
|
- **Kein Python:** einzige externe Abhängigkeit ist `npx pagefind` (Suchindex, optional)
|
|
- **Funktionen:** Markdown + YAML-Frontmatter → statisches HTML pro Sprache,
|
|
Navigation, SEO-Kopf (OpenGraph/JSON-LD), `sitemap.xml`, `robots.txt`,
|
|
Mermaid-Diagramme, client-seitige Volltextsuche (Pagefind), UI-Lokalisierung
|
|
über `{{ i18n.* }}`, optionaler Machine-Translation-Helfer (Entwürfe),
|
|
Markdown-Rendering im Terminal via `webstatic status`.
|
|
|
|
## Schnellstart
|
|
|
|
```bash
|
|
# Tool bauen
|
|
dotnet build -c Release
|
|
|
|
# Beispiel-Seite erzeugen und bauen
|
|
dotnet bin/Release/net10.0/webstatic.dll init mysite
|
|
cd mysite
|
|
dotnet ../../bin/Release/net10.0/webstatic.dll build --env development
|
|
|
|
# Lokal ansehen
|
|
dotnet ../../bin/Release/net10.0/webstatic.dll serve --port 8000
|
|
|
|
# Site-Status (README.md im Terminal rendern)
|
|
dotnet ../../bin/Release/net10.0/webstatic.dll status
|
|
```
|
|
|
|
## CLI-Befehle
|
|
|
|
| Befehl | Bedeutung |
|
|
|--------|-----------|
|
|
| `webstatic build [Optionen]` | Website bauen |
|
|
| `webstatic serve [--port N]` | Lokalen Server starten (Vorschau) |
|
|
| `webstatic init <name>` | Beispiel-Site anlegen |
|
|
| `webstatic status [--root DIR]` | README.md der Site im Terminal anzeigen |
|
|
| `webstatic translate --check` | Fehlende Übersetzungen melden |
|
|
| `webstatic translate --draft` | Übersetzungs-Entwürfe erzeugen |
|
|
| `webstatic --version` | Version (Assembly + Git-Commit) anzeigen |
|
|
| `webstatic --help \| -h` | Hilfe anzeigen |
|
|
| `webstatic update` | Selbstaktualisierung (Clone-Installation) |
|
|
|
|
## Umgebungen
|
|
|
|
| `--env` | baseUrl (Beispiel) | Zweck |
|
|
|--------------|------------------------------|------------------------|
|
|
| `development`| `http://localhost:8000` | Lokale Entwicklung (work/preview/review) |
|
|
| `staging` | `https://gcbok.gitcover.org` | Abnahme (brx5) |
|
|
| `deploy` | `https://gcbok.org` | Production |
|
|
|
|
Aliase: `--preview` / `--work` / `--review` = `development`, `--staging` = `staging`, `--deploy` = `deploy`.
|
|
|
|
## Konfiguration (`webstatic.json`)
|
|
|
|
CLI-Flags haben Vorrang vor `webstatic.json`, dieses vor eingebauten Defaults.
|
|
Siehe `webstatic.example/webstatic.json` und `docs/getting-started.md`.
|
|
|
|
## Installation für KMU
|
|
|
|
```bash
|
|
./install.sh # -> /opt/GitCover/webstatic, Symlink /usr/local/bin/webstatic
|
|
```
|
|
|
|
## Version & Update
|
|
|
|
Die Versionsnummer wird an drei Stellen synchron gehalten (Definition of Done
|
|
für jeden Release-Commit):
|
|
|
|
1. **`README.md`** — Block-Quote direkt unter dem Titel (kanonisch, per Remote
|
|
via `git show origin/main:README.md` sichtbar)
|
|
2. **`GCBoK.WebStaticBuilder.csproj`** — `<Version>1.0.0</Version>` (Assembly)
|
|
3. **`webstatic --version`** — gibt die Assembly-Version aus
|
|
|
|
So kann vor einem Update sowohl lokal (im Installations-Repo) als auch remote
|
|
(im Upstream-Repo) die Version festgestellt werden, ohne die CLI aufzurufen:
|
|
|
|
```bash
|
|
# Lokal installierte Version (Clone-Installation)
|
|
git -C /opt/GitCover/webstatic show HEAD:README.md | head -3
|
|
|
|
# Remote verfügbare Version (vor Pull)
|
|
git -C /opt/GitCover/webstatic show origin/main:README.md | head -3
|
|
```
|
|
|
|
### Update-Check via CLI
|
|
|
|
`webstatic --version` führt automatisch einen Remote-Check durch
|
|
(`git ls-remote origin HEAD`) und vergleicht lokalen mit remote Commit-Hash:
|
|
|
|
```bash
|
|
webstatic --version
|
|
# GCBoK.WebStaticBuilder 1.0.0.0
|
|
# commit: 6ca8167 (local)
|
|
# remote: ff634a3
|
|
#
|
|
# UPDATE AVAILABLE
|
|
# Run: webstatic update
|
|
```
|
|
|
|
Bei Copy-Installationen (kein `.git`) entfällt der Remote-Check; das Tool weist
|
|
auf `./install.sh` als Update-Weg hin.
|
|
|
|
### Update durchführen
|
|
|
|
```bash
|
|
webstatic update # Selbstaktualisierung (Clone-Installation): lokale
|
|
# Änderungen werden gestasht, git pull, gemerged, neu gebaut
|
|
```
|
|
|
|
`webstatic update` setzt eine Clone-Installation voraus (siehe `install.sh`,
|
|
Default `WEBSTATIC_INSTALL_MODE=clone`). Bei einer Copy-Installation erfolgt das
|
|
Update via erneutem `./install.sh`.
|
|
|
|
## Machine Translation (optional)
|
|
|
|
```bash
|
|
webstatic translate --check # fehlende Übersetzungen melden
|
|
export WEBSTATIC_TRANSLATOR_KEY=... # API-Key (Azure/DeepL)
|
|
webstatic translate --draft # Entwürfe nach .translation-drafts/
|
|
```
|
|
|
|
Entwürfe überschreiben niemals Quelldateien.
|
|
|
|
## Verzeichnisstruktur
|
|
|
|
```
|
|
plans/ Produktplan & Folgepläne
|
|
docs/ Anleitungen (KMU, Admin)
|
|
diary/ Entwicklungs-Tagebuch
|
|
src/ C#-Quellcode (GCBoK.WebStaticBuilder)
|
|
tests/ (künftig) Unit/Integrationstests
|
|
webstatic.example/ Vorlage-Site für KMU
|
|
install.sh KMU-Installation
|
|
LICENSE MIT + Third-Party-Dependency-Lizenzen
|
|
```
|