From: Kai Moritz Date: Wed, 17 Jun 2026 19:31:17 +0000 (+0000) Subject: Rename CLAUDE.md to README.md X-Git-Url: http://juplo.de/gitweb/?a=commitdiff_plain;h=c48f15ceb9137fc002d4020f1439d774123f608d;p=maven-thymeleaf-skin Rename CLAUDE.md to README.md --- diff --git a/CLAUDE.md b/CLAUDE.md deleted file mode 100644 index 529c0ea..0000000 --- a/CLAUDE.md +++ /dev/null @@ -1,254 +0,0 @@ -# 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. -- Änderungen immer so vornehmen, dass die Diffs minimal sind und sich gut per Review kontrollieren lassen: nur ändern, was tatsächlich geändert werden muss — keine Umformatierungen, Umstrukturierungen oder Neusortierungen, die nichts zur eigentlichen Änderung beitragen. - -## 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. -- Nach jedem Commit wird gemeinsam geprüft, ob der Build noch zufriedenstellend funktioniert, bevor der nächste Schritt angegangen wird. - -## Maven Wrapper - -Das Projekt verwendet den **Maven Wrapper** (`mvnw` / `mvnw.cmd`), der Maven 3.9.6 automatisch herunterlädt falls es nicht lokal vorhanden ist. - -```bash -./mvnw clean site # statt: mvn clean site -./mvnw wrapper:wrapper # Wrapper-Dateien neu generieren (erfordert Maven) -``` - -**Dateien:** -- `.mvn/wrapper/maven-wrapper.properties` — Maven-Version und Download-URL (Single Source of Truth für die Maven-Version des Wrappers) -- `mvnw` — Unix-Startskript (Apache Maven Wrapper 3.3.2) -- `mvnw.cmd` — Windows-Startskript (Apache Maven Wrapper 3.3.2) - -**Maven-Version aktualisieren:** Nur in `maven-wrapper.properties` die `distributionUrl` und den Dateinamen ändern. Die Wrapper-Skripte selbst (`mvnw`, `mvnw.cmd`) müssen nur neu generiert werden, wenn die Wrapper-Version selbst geändert wird — dazu auf einem Rechner mit installiertem Maven `mvn -N wrapper:wrapper -Dmaven=` ausführen und die generierten Dateien committen. - -## Maven-Site-Dokumentation - -Die Projektdokumentation liegt unter `src/site/` und wird mit `mvn site` gerendert. -Diese CLAUDE.md ist die **Single Source of Truth (SSOT)** für den inhaltlichen Teil der Dokumentation. -Die Markdown-Dateien unter `src/site/markdown/` sind aus dieser CLAUDE.md abgeleitet und werden -**manuell auf Anforderung** neu generiert — nicht automatisch vor jedem Release. - -### Struktur - -``` -src/site/ - site.xml ← Navigation, Skin (maven-fluido-skin), Menüname - markdown/ - index.md ← Übersicht: Name, Ziel, Quick Start, Community-Prinzip - architecture.md ← Technisches: site.vm, stili-json-Format, Seitentypen, Body-Extraktion - import-in-hugo.md ← Referenz: Hugo-Import-Skript - import-in-astro.md ← Referenz: Astro-Import-Skript -``` - -**Mapping CLAUDE.md → Dokumentation:** - -| CLAUDE.md-Abschnitt | Datei | -|---|---| -| Was ist StILi? + Architektur-Prinzip | `index.md` | -| Funktionsweise: site.vm + JSON-Struktur + Seitentypen + Extraktion | `architecture.md` | -| Import-Skripte → import-in-hugo.sh | `import-in-hugo.md` | -| Import-Skripte → import-in-astro.sh | `import-in-astro.md` | - -### Wann neu generieren? - -Nur bei **inhaltlichen Änderungen** an den folgenden CLAUDE.md-Abschnitten: - -- „Was ist StILi?" oder „Architektur-Prinzip" -- „Funktionsweise: site.vm" oder „JSON-Struktur" oder „Seitentypen" oder „Extraktion" -- „Import-Skripte" (Parameter, Ausgaben, Beispiele) - -Nicht neu generieren für: Arbeitsregeln, Commit-Anweisungen, reine Formulierungsänderungen ohne Informationsgewinn. - -### Wie neu generieren (Aufruf für Claude Code) - -**Trigger:** `"Bitte generiere die Maven-Site-Dokumentation neu"` oder sinngemäß. - -**Vorgehen:** -1. Lies die inhaltlich relevanten Abschnitte dieser CLAUDE.md -2. Überarbeite **nur** die betroffenen Stellen in den entsprechenden Markdown-Dateien (Mapping siehe oben) -3. Halte Formatierung, Überschriften-Hierarchie und Tabellenstruktur stabil — ändere nur was sich inhaltlich geändert hat -4. Committe die aktualisierten Dateien - -**Prinzip für minimale Diffs:** Jeder inhaltliche Unterschied zur CLAUDE.md erzeugt genau einen entsprechenden Diff in der Dokumentation — kein Rauschen durch Umformatierung, Neustrukturierung oder Neusortierung. - ---- - -## Was ist StILi? - -**StILi** steht für **(St)atic (I)mport site (Li)berator** — und der Name ist dabei Programm: - -- **Liberator**: Maven generiert Site-Inhalte in einem Monolith-HTML-Format, das nur im Kontext des Maven-eigenen Themes nutzbar ist. StILi _befreit_ diesen Inhalt: Die Skin serialisiert Struktur und Metadaten in ein maschinenlesbares JSON-Format und macht damit den Inhalt für beliebige weitere Werkzeuge zugänglich. -- **Static**: Das Ziel sind statische Site-Generatoren — Hugo, Astro, und alles weitere, was jemand ergänzt. -- **Import**: Der Mechanismus sind Import-Skripte, die den generierten Maven-Output in das Ziel-System übertragen. -- **Site**: Es handelt sich um Maven-Site-Output (Doxia). - -Der Name klingt zudem bewusst wie das deutsche/englische/italienische Wort für _Stil_ bzw. _stile_ — als Anspielung darauf, dass die Skin den Inhalt auf stilvolle Weise aus dem Maven-Korsett befreit. - -### Architektur-Prinzip: Erweiterbar durch die Community - -StILi ist kein juplo.de-spezifisches Werkzeug. Das Ziel ist ein allgemein verwendbares Maven-Doxia-Skin für beliebige Projekte. Die Skin selbst ist generator-agnostisch — sie kümmert sich nur darum, den Inhalt und die Navigationsstruktur maschinenlesbar zu machen. - -Die zielspezifische Logik steckt in den Import-Skripten, die die Skin als Maven-Resources mitliefert: - -``` -src/main/resources/ - META-INF/maven/site.vm ← Die Skin selbst (generator-agnostisch) - import-in-hugo.sh ← Import-Skript für Hugo - import-in-astro.sh ← Import-Skript für Astro - (import-in-eleventy.sh) ← Zukünftige Community-Beiträge denkbar -``` - -Wer StILi mit einem anderen Generator nutzen möchte, schreibt ein neues Import-Skript und kann es als Community-Beitrag zurückfließen lassen. - ---- - -## 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 -

Seitentitel

-
- $bodyContent -
-``` - -**Nur für `index.html`** wird zusätzlich ein JSON-Metadaten-Block angehängt: - -```html - -``` - -### 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 '/ +``` + +### 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 '/