build_webstatic/docs/getting-started.md

Getting Started (KMU)

Diese Anleitung beschreibt, wie Sie mit GitCover.WebStaticBuilder eine eigene, mehrsprachige, statische Website erstellen — ohne Server, Datenbank oder JavaScript-Framework.

1. Voraussetzungen

• .NET 10 SDK (dotnet) — https://dotnet.microsoft.com/download
• Optional: Node.js (für die Suchfunktion Pagefind). Ohne Node wird die Seite gebaut, die Suche entfällt (nicht fatal).

2. Installation

git clone <repo> build_webstatic
cd build_webstatic
./install.sh          # per-user: ~/.local/share/GitCover/webstatic (Default, Betatester)

Die per-user Betatester-Installation (Default) legt ein echtes Git-Repo unter ~/.local/share/GitCover/webstatic an und setzt den Launcher ~/.local/bin/webstatic. Updates erfolgen ohne sudo via webstatic update (stash/pull/merge/rebuild — Hermes-Konzept). Eine optionale System-Installation (root) unter /opt/GitCover/webstatic ist via WEBSTATIC_INSTALL_DIR=/opt/GitCover/webstatic WEBSTATIC_BIN_DIR=/usr/local/bin ./install.sh möglich. Nach der Installation ist webstatic im PATH verfügbar.

3. Neue Website anlegen

webstatic init mysite
cd mysite

Das erzeugt eine Vorlage (webstatic.example/) mit:

• webstatic.json — Konfiguration (Sprachen, Umgebungen, Pfade)
• i18n.json — UI-Übersetzungen
• content/ — Markdown-Inhalte
• templates/layout.html — HTML-Grundgerüst
• assets/ — CSS, JS, Favicon

4. Inhalte pflegen

Jede Seite ist eine Markdown-Datei mit YAML-Frontmatter am Anfang:

---
section: start
order: 1
eyebrow: "Startseite"
title: "Startseite"
description: "Die Landing-Page"
href: /
render: true
navbar: true
---

## Einführung
Ihr Inhalt …

• order steuert die Reihenfolge in Navigation und Sidebar.
• order: 0 = Banner (eigene Seite, getrennt vom Hero/order: 1).
• Sprachvarianten: 02-start.de.md (Default), 02-start.en.md, 02-start.vi.md (fehlende Sprache fällt auf .de.md zurück).

Wichtig — Titel/Eyebrow erscheinen NICHT automatisch als Überschrift. title und eyebrow aus dem Frontmatter speisen nur <title>/Meta (SEO) und die Navigations-Labels. webstatic stellt kein {{ title }}/{{ eyebrow }} Seitentoken bereit. Tragen Sie Eyebrow + Titel daher selbst im Body der jeweiligen Markdown-Datei ein (z. B. als <p class="eyebrow">…</p> + <h1>…</h1>), sonst fehlen die sichtbaren Überschriften auf der Seite.

5. Bauen & Vorschau

webstatic build --env development   # localhost:8000
webstatic serve --port 8000         # lokaler Server (Strg+C beendet)

Die client-seitige Volltextsuche (Pagefind) wird im Post-Build erzeugt, sofern Node.js vorhanden ist. Mit "pagefind": false in webstatic.json wird sie komplett deaktiviert (Such-Toggle im Chrome dann nicht funktional) — nützlich, wenn eine Site keinen Index benötigt.

6. Veröffentlichen

Ziel	Befehl
Development (lokal; --preview/--work/--review = development)	webstatic build --env development
Staging	webstatic build --env staging
Production	webstatic build --env deploy

Die erzeugte dist/-Aufgabe wird auf den jeweiligen Webspace kopiert.

7. UI übersetzen

Texte im Layout (templates/layout.html) nutzen Platzhalter {{ i18n.<bereich>.<schluessel> }}. Die Werte stehen in i18n.json (pro Sprache). Fehlende Schlüssel bleiben als Platzhalter sichtbar — so erkennen Sie Lücken sofort.

8. Machine Translation (optional)

webstatic translate --check                       # welche Sprachen fehlen?
export WEBSTATIC_TRANSLATOR_KEY=<ihr-key>         # Azure oder DeepL
webstatic translate --draft                       # Entwürfe in .translation-drafts/

Entwürfe überschreiben niemals Ihre Quelldateien — sie sind zum Nacharbeiten gedacht.