README.md

AGENTS.md

@@ -0,0 +1,30 @@
+# AGENTS.md
+
+## Wichtigste Regel: Parser NICHT erneut ausführen
+
+Der Parser `scripts/parse_buildbroken_archive.py` wurde **einmalig** genutzt, um die
+Blogartikel aus den Wayback-HTML-Dateien zu generieren. Die Artikel in
+`content/posts/*.md` wurden danach **manuell ausgebessert** (Titel gekürzt,
+Tags korrigiert, `alt`-Attribute ergänzt, Links umgeschrieben). Ein erneuter
+Parser-Lauf würde diese Handarbeit überschreiben und ist daher **verboten**.
+
+Das gilt ebenso für `--download-images`: Bilder und Zuweisungen sind bereits
+final; nichts neu herunterladen.
+
+## Grundregeln
+
+- **Kein `hugo server` im Hintergrund laufen lassen, wenn `public/` deployt
+  werden soll** – der Dev-Server überschreibt `public/` laufend mit
+  unminifizierten Dev-Artefakten (`livereload.js`). Für den Produktionsstand:
+  `hugo --minify --cleanDestinationDir`.
+- **Deployment:** Cloudflare-Workers über `wrangler.json`
+  (`assets.directory: public`, `not_found_handling: 404-page`).
+- **Content** in `content/posts/*.md` und `content/_index.md` wird von Hand
+  gepflegt. Titel sollen unter ~60 Zeichen bleiben.
+- **SEO-Metadaten** werden zentral in `layouts/_default/baseof.html` erzeugt
+  (description/canonical/OG/Twitter). Keine Per-Post-Hardcodes außer nötig.
+- **Bilder** in Posts brauchen ein `alt`-Attribut; der Banner ist dekorativ
+  (`alt=""`).
+- Die Startseite enthält den About-Text (kein eigenes `/about/` mehr);
+  `about.html`-Redirects zeigen auf `/`.
+- **Commits:** ohne Co-Autoren; nur der eigentliche Autor.

README.md

@@ -69,6 +69,10 @@ buildbroken-blog-archive/
    pip install -r requirements.txt
    python parse_buildbroken_archive.py --source ../archive/wayback-html --output .. --download-images
    ```
+   > **Wichtig:** Der Parser soll **nicht mehr erneut ausgeführt** werden. Die
+   > generierten Artikel in `content/posts/*.md` wurden nachträglich manuell
+   > ausgebessert (Titel gekürzt, Tags korrigiert, `alt`-Attribute ergänzt,
+   > Links umgeschrieben). Ein erneuter Lauf würde diese Handarbeit überschreiben.
 3. Lokale Vorschau:
    ```bash
    cd ..
@@ -104,6 +108,23 @@ Die `wrangler.json` im Projekt-Root konfiguriert das Deployment:
 - `name`: Projektname (`buildbroken-blog-archive`)
 - `compatibility_date`: Datum der Cloudflare-Laufzeit
 - `assets.directory`: `public` — das Hugo-Ausgabeverzeichnis, das bereitgestellt wird
+- `assets.not_found_handling`: `404-page` — liefert die eigene `public/404.html` (statt eines generischen 404) für nicht gefundene Pfade
+
+## SEO
+
+Das Layout erzeugt für jede Seite automatisch SEO-Metadaten (zentral in
+`layouts/_default/baseof.html`):
+
+- `meta name="description"` (aus Frontmatter/`.Description`, sonst aus `.Summary`; für Taxonomie-, Autor- und Archiv-Seiten generisch formuliert, auf ~160 Zeichen gekürzt)
+- `link rel="canonical"` mit der absoluten URL
+- Open-Graph- und Twitter-Card-Tags (`og:type` article/website, `og:image` Banner, `twitter:card` summary_large_image)
+- `<title>`: Tag- und Kategorie-Seiten werden differenziert (`MVC (Tag)` vs. `MVC (Kategorie)`), Länge auf ~60 Zeichen begrenzt
+
+Außerdem:
+
+- Eigene `layouts/_default/404.html`, die via `assets.not_found_handling: "404-page"` von Cloudflare ausgeliefert wird
+- `robots.txt` verweist auf `sitemap.xml` (Hugo-generiert)
+- Content-Bilder in `content/posts/*.md` tragen `alt`-Attribute; der dekorative Banner hat bewusst leeres `alt=""`
 
 ## Layout anpassen