From 4a9502150ce1cc134e8c5615f08b9108f8abb614 Mon Sep 17 00:00:00 2001
From: Kai Moritz <kai.milan.moritz@googlemail.com>
Date: Tue, 16 Jun 2026 18:19:47 +0000
Subject: [PATCH] Add CLAUDE.md documenting skin architecture and import
 scripts

Covers site.vm behavior, sili-json structure, page types, body
extraction, and both import scripts with their target-system specifics.

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

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..753baa0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,141 @@
+# CLAUDE.md
+
+Diese Datei enthält Anweisungen für Claude Code (claude.ai/code) beim Arbeiten mit diesem Repository.
+
+## Arbeitsregeln
+
+- Ab und zu bin ich ungenau oder bringe Details durcheinander. Wenn du den Eindruck hast, dass etwas nicht passt oder Details fehlen, frage immer direkt nach.
+- Für alle Aufgaben gilt: du kannst und sollst Nachfragen stellen, bevor du mit der Umsetzung beginnst, wenn das sinnvoll ist.
+
+## Commits
+
+- Erstelle nach dem Abschluss einer Aufgabe jeweils einen Commit — direkt, ohne vorher nachzufragen.
+- Fasse in der Commit-Nachricht zusammen, was und warum geändert wurde.
+
+---
+
+## Zweck
+
+`maven-sili-skin` ist eine Maven-Doxia-Skin, die Maven-Site-Output für den Import in statische Website-Generatoren aufbereitet. Die Skin erzeugt HTML-Seiten mit eingebettetem JSON-Metadaten-Block, den die Import-Skripte auslesen.
+
+## Funktionsweise: `site.vm`
+
+Das Velocity-Template `src/main/resources/META-INF/maven/site.vm` ist das Herzstück der Skin. Es rendert jede Maven-Seite so:
+
+```html
+<h1 id="sili-title">Seitentitel</h1>
+<div id="sili-body">
+  $bodyContent
+</div>
+```
+
+**Nur für `index.html`** wird zusätzlich ein JSON-Metadaten-Block angehängt:
+
+```html
+<script id="sili-json" type="application/json">
+{
+  "project": "Projektname",
+  "groupId": "de.juplo",
+  "artifactId": "hibernate-maven-plugin",
+  "version": "2.1.1",
+  "pages": [ ... ]
+}
+</script>
+```
+
+### JSON-Struktur: `pages`-Array
+
+Das `pages`-Array enthält alle Seiten der Maven-Site in der Reihenfolge, in der sie im Menü auftauchen. Die Position im Array dient als `weight` für die Nav-Sortierung.
+
+Jeder Eintrag:
+
+```json
+{
+  "name": "Project Reports",
+  "href": "project-reports.html",
+  "childs": ["plugin-info.html"],
+  "crumbs": [],
+  "path": ""
+}
+```
+
+- `href`: Dateiname relativ zum Site-Root (z.B. `project-reports.html`, bei Verzeichnissen z.B. `apidocs/index.html`)
+- `childs`: direkte Kinder im Menübaum (nur deren `href`-Werte)
+- `crumbs`: Vorfahren von der Wurzel aus (ohne `index.html`), z.B. `["project-reports.html"]`
+- `path`: Vorfahren als Verzeichnispfad — `crumbs` mit `.html` → `/` substituiert, z.B. `"project-reports/"` oder `"project-reports/plugin-info/"`
+
+### Seitentypen im Maven-Output
+
+| Typ | Beispiel | Erkennung |
+|---|---|---|
+| Root | `index.html` | `href == "index.html"` |
+| Section-Node (hat Kinder) | `project-reports.html` | `childs.length > 0` |
+| Blatt-Seite | `configuration.html` | `childs.length == 0` |
+| Generierter Content | `apidocs/`, `xref/` etc. | Verzeichnis, nicht HTML-Datei |
+
+Generierter Content (JavaDocs, Xref etc.) erscheint als Unterverzeichnis im Maven-Site-Output und hat einen Eintrag in `pages` mit `href` wie `apidocs/index.html`.
+
+### Extraktion des Body-Inhalts
+
+Aus den HTML-Dateien wird der Body so extrahiert:
+
+```bash
+sed -n '/<script id="sili-json" type="application\/json">/q;p' "$SOURCE" \
+  | tail -n +2
+```
+
+- `sed` gibt alle Zeilen vor dem JSON-Block aus (und stoppt; bei Nicht-`index.html`-Dateien gibt es keinen JSON-Block, also alles)
+- `tail -n +2` entfernt die erste Zeile (`<h1 id="sili-title">...`)
+
+## Import-Skripte
+
+Die Skin liefert zwei Import-Skripte als Maven-Resource mit. Sie werden bei `mvn site` in das Site-Output-Verzeichnis kopiert und von dort ausgeführt:
+
+```bash
+cd target/site
+./import-in-astro.sh /pfad/zum/astro-projekt [Optionen]
+```
+
+### `import-in-hugo.sh` — Import in Hugo
+
+Importiert Maven-Site-Output in ein Hugo-Projekt:
+
+- HTML-Seiten → `content/$BASE/$PROJECT/$VERSION/` (mit YAML-Frontmatter inkl. `outputs`, `layout`)
+- Generierter Content → `static/$URL_BASE/`
+- Verzeichnisse mit Menüeintrag erhalten zusätzlich eine Hugo-Content-Seite mit JS-Redirect auf den statischen Inhalt
+- `<pre>`-Blöcke werden via `perl` in Hugo-`{{< highlight >}}`-Shortcodes umgewandelt
+
+Die Option `--base` ermöglicht ein URL-Präfix-Verzeichnis (z.B. `--base /projects`).
+
+### `import-in-astro.sh` — Import in Astro
+
+Importiert Maven-Site-Output in ein Astro-Projekt (juplo.de-Website):
+
+- HTML-Seiten → `src/content/projects/$PROJECT/$VERSION/` (YAML-Frontmatter ohne Hugo-Felder)
+- Routing-Dateien → `src/pages/$PROJECT/` (current) oder `src/pages/projects/$PROJECT/$VERSION/` (archived)
+- Generierter Content → `public/projects/$PROJECT/$VERSION/`
+- Relative Links auf generierte Verzeichnisse (`apidocs/`, `xref/` etc.) werden zu absoluten URLs mit explizitem `/index.html` umgeschrieben, da die generierten Inhalte immer unter `/projects/X/Y/` liegen — unabhängig davon, ob die Content-Seite unter der sichtbaren URL (`/<project>/`) oder der archivierten URL (`/projects/X/Y/`) ausgeliefert wird
+
+#### Seitenstruktur im Astro-Projekt
+
+Section-Nodes (Seiten mit Kinder-Einträgen) werden zu `_index.html` in einem Unterverzeichnis:
+
+| Maven-Output | Content-Pfad | URL (current) |
+|---|---|---|
+| `index.html` | `_index.html` | `/<project>/` |
+| `project-reports.html` (hat Kinder) | `project-reports/_index.html` | `/<project>/project-reports.html` |
+| `plugin-info.html` (hat Kinder, Kind von project-reports) | `project-reports/plugin-info/_index.html` | `/<project>/plugin-info.html` |
+| `create-mojo.html` (Blatt) | `project-reports/plugin-info/create-mojo.html` | `/<project>/create-mojo.html` |
+
+URLs sind immer **flach** (kein URL-Nesting entsprechend der Content-Hierarchie) — spiegelt Mavens eigene flache Site-Struktur wider.
+
+#### Bekannte generierte Verzeichnisse
+
+Die folgenden Verzeichnisse werden vom Astro-Projekt als Nav-Einträge erkannt (definiert in `src/lib/projects.ts`, `GENERATED_DOC_NAMES`):
+
+| Verzeichnis | Nav-Bezeichnung |
+|---|---|
+| `apidocs/` | JavaDocs |
+| `testapidocs/` | Test JavaDocs |
+| `xref/` | Source Xref |
+| `xref-test/` | Test Source Xref |
-- 
2.39.5