From 59a8d4af705ee688d506277d58392c355a0cbacf Mon Sep 17 00:00:00 2001
From: Kai Moritz <kai.milan.moritz@googlemail.com>
Date: Sun, 14 Jun 2026 12:06:05 +0000
Subject: [PATCH] CLAUDE.md: Projects-Content-Architektur und
 Tooling-Anforderungen dokumentiert
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

Neue Sektion im Astro-Abschnitt erklärt das Verzeichnislayout unter
src/content/projects/, das Frontmatter-Schema für sichtbare und nicht
sichtbare Versionen, das Mapping zwischen Content-Dateien und
Routing-Dateien in src/pages/, den .html-URL-Quirk in Astro sowie
die Behandlung generierter Inhalte (apidocs, xref etc.) über
public/projects/.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 86 insertions(+)

diff --git a/CLAUDE.md b/CLAUDE.md
index 5294c3de..04149550 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -275,6 +275,92 @@ Wenn Projects implementiert wird: `blogSectionOff |= onProjectsSection`, `aboutO
 
 ---
 
+#### Projects: Content-Architektur und Anforderungen ans Tooling
+
+Projektdokumentation liegt in `src/content/projects/PROJEKT_NAME/VERSION/` als HTML-Dateien mit YAML-Frontmatter. Ein Custom Loader in `src/content.config.ts` (mit `js-yaml`) liest diese ein; Routing und Nav-Logik werden in `src/lib/projects.ts` und `BlogNav.astro` verwaltet.
+
+**Verzeichnisstruktur (Beispiel hibernate-maven-plugin):**
+```
+src/content/projects/
+└── hibernate-maven-plugin/
+    ├── 2.1.1/                          ← sichtbare Version (params.current: true)
+    │   ├── _index.html                 ← Einstiegsseite (section-node im Nav)
+    │   ├── configuration.html
+    │   ├── project-info/
+    │   │   └── _index.html            ← section-node
+    │   └── project-reports/
+    │       ├── _index.html            ← section-node
+    │       └── plugin-info/
+    │           ├── _index.html        ← section-node
+    │           └── create-mojo.html
+    └── 2.1.2-SNAPSHOT/                 ← nicht sichtbare Version (params.current: false)
+        └── (identische Struktur)
+```
+
+`_index.html`-Dateien markieren section-nodes (rendern `<li class="s sub">` im Nav). Alle anderen `.html`-Dateien sind Blatt-Seiten.
+
+**Frontmatter-Schema** (YAML zwischen `---`, dann HTML-Body):
+
+Sichtbare Version (`params.current: true`) — `url` ist die kanonische SEO-URL:
+```yaml
+---
+title: "Hibernate Maven Plugin – Configuration"
+url: /hibernate-maven-plugin/configuration.html
+params:
+  current: true
+---
+```
+
+Nicht sichtbare Version (`params.current: false`) — `url` folgt dem Muster `/projects/X/Y/PAGE.html`, `params.canonical` verweist auf die sichtbare Entsprechung:
+```yaml
+---
+title: "Hibernate Maven Plugin – Configuration"
+url: /projects/hibernate-maven-plugin/2.1.2-SNAPSHOT/configuration.html
+params:
+  current: false
+  canonical: /hibernate-maven-plugin/configuration.html
+---
+```
+
+Für `_index.html`-section-nodes endet die `url` ohne `.html` (z.B. `url: /hibernate-maven-plugin/`).
+
+**Routing-Dateien** in `src/pages/`:
+
+Für jede Content-Datei muss das Tooling eine korrespondierende statische `.astro`-Datei erzeugen. Das Mapping folgt direkt dem `url`-Feld:
+
+| Content-Datei | `url`-Feld | Routing-Datei |
+|---|---|---|
+| `2.1.1/_index.html` | `/hibernate-maven-plugin/` | `src/pages/hibernate-maven-plugin/index.astro` |
+| `2.1.1/configuration.html` | `/hibernate-maven-plugin/configuration.html` | `src/pages/hibernate-maven-plugin/configuration.html.astro` |
+| `2.1.1/project-reports/_index.html` | `/hibernate-maven-plugin/project-reports.html` | `src/pages/hibernate-maven-plugin/project-reports.html.astro` |
+| `2.1.2-SNAPSHOT/_index.html` | `/projects/hibernate-maven-plugin/2.1.2-SNAPSHOT/` | `src/pages/projects/hibernate-maven-plugin/2.1.2-SNAPSHOT/index.astro` |
+| `2.1.2-SNAPSHOT/configuration.html` | `/projects/hibernate-maven-plugin/2.1.2-SNAPSHOT/configuration.html` | `src/pages/projects/hibernate-maven-plugin/2.1.2-SNAPSHOT/configuration.html.astro` |
+
+Inhalt jeder Routing-Datei (immer dasselbe Minimal-Template):
+```astro
+---
+import ProjectPage from '<relativer-pfad>/components/ProjectPage.astro';
+---
+<ProjectPage entryId="PROJEKT_NAME/VERSION/relativer/pfad.html" />
+```
+
+Die `entryId` ist der relative Pfad innerhalb von `src/content/projects/` (ohne dieses Präfix), also z.B. `"hibernate-maven-plugin/2.1.1/project-reports/_index.html"`.
+
+**`.html`-URL-Quirk:** `configuration.html.astro` erzeugt im Build `configuration.html/index.html` (Astro verwendet immer Directory-Style). Nginx serviert das korrekt via Directory-Index — identisches Verhalten wie bei den About-Seiten (`/contact.html` etc.).
+
+**Generierte Inhalte** (apidocs, xref etc.): Der statische Maven-Site-Output wird direkt in `public/projects/PROJEKT_NAME/VERSION/` abgelegt — kein `src/content/`-Eintrag, keine Routing-Datei. `src/lib/projects.ts` (`generatedDocNodes()`) erkennt diese Verzeichnisse automatisch zur Build-Zeit und erzeugt Nav-Einträge.
+
+Erkannte Unterverzeichnisse in `public/projects/X/Y/`:
+
+| Verzeichnis | Nav-Bezeichnung |
+|---|---|
+| `apidocs/` | API-Docs |
+| `testapidocs/` | Test-API-Docs |
+| `xref/` | Quelltext |
+| `xref-test/` | Test-Quelltext |
+
+---
+
 #### Hugo-Dateien entfernt nach Migration
 
 **Was:** Nach Abschluss der Astro-Migration wurden folgende Hugo-spezifische Dateien und Verzeichnisse aus dem Repo entfernt:
-- 
2.39.5