-# CLAUDE.md
+# Maven StILi Skin
-Diese Datei enthält Anweisungen für Claude Code (claude.ai/code) beim Arbeiten mit diesem Repository.
+[](LICENSE)
-## Arbeitsregeln
+A Maven Doxia skin that liberates generated site content and its navigation structure for import into arbitrary static site generators.
-- 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.
+**StILi** = **(St)atic (I)mport site (Li)berator**
-## Commits
+## What is StILi?
-- 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 generates site content as monolithic HTML pages that are only usable within the Maven theme ecosystem. StILi *liberates* that content by serialising page structure and metadata into a machine-readable JSON block, making it accessible to any downstream tool.
-## Maven Wrapper
+The intended targets are static site generators — Hugo, Astro, and any generator for which someone contributes an import script. Generator-specific logic lives in import scripts shipped as Maven resources alongside the skin.
-Das Projekt verwendet den **Maven Wrapper** (`mvnw` / `mvnw.cmd`), der Maven 3.9.6 automatisch herunterlädt falls es nicht lokal vorhanden ist.
+The name also echoes the German/Italian word for *style* (*Stil* / *stile*) — a nod to the fact that StILi liberates Maven site content in a stylish way.
-```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=<version>` 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.
+## Quick Start
-### Struktur
+Add StILi as the skin in your project's `src/site/site.xml`:
+```xml
+<project ...>
+ <skin>
+ <groupId>de.juplo.maven</groupId>
+ <artifactId>maven-stili-skin</artifactId>
+ <version>1.0.0</version>
+ </skin>
+ <custom>
+ <menuName>Your Main Menu Name</menuName>
+ </custom>
+ ...
+</project>
```
-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:
+The `<menuName>` element tells StILi which menu in `site.xml` is the primary navigation — it determines the page order and hierarchy recorded in the generated JSON block.
-- „Was ist StILi?" oder „Architektur-Prinzip"
-- „Funktionsweise: site.vm" oder „JSON-Struktur" oder „Seitentypen" oder „Extraktion"
-- „Import-Skripte" (Parameter, Ausgaben, Beispiele)
+After running `mvn site`, the generated output in `target/site/` contains the regular HTML files plus the import scripts. Run the appropriate script from that directory:
-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.
+```bash
+cd target/site
+./import-in-astro.sh /path/to/your/astro-project --current
+```
-### Architektur-Prinzip: Erweiterbar durch die Community
+## Design Principle: Extensible by the 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.
+StILi is not tied to any specific website or static site generator. The skin itself is completely generator-agnostic — it only ensures that content and navigation structure are machine-readable.
-Die zielspezifische Logik steckt in den Import-Skripten, die die Skin als Maven-Resources mitliefert:
+Generator-specific logic lives in import scripts, which the skin ships as Maven resources:
-```
-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
-```
+| Script | Target |
+|---|---|
+| `import-in-hugo.sh` | Hugo |
+| `import-in-astro.sh` | Astro |
-Wer StILi mit einem anderen Generator nutzen möchte, schreibt ein neues Import-Skript und kann es als Community-Beitrag zurückfließen lassen.
+Anyone who wants to use StILi with a different generator writes a new import script. Contributions are welcome.
----
+## How It Works
-## Funktionsweise: `site.vm`
+### `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:
+The Velocity template `src/main/resources/META-INF/maven/site.vm` renders each Maven page as:
```html
-<h1 id="stili-title">Seitentitel</h1>
+<h1 id="stili-title">Page title</h1>
<div id="stili-body">
$bodyContent
</div>
```
-**Nur für `index.html`** wird zusätzlich ein JSON-Metadaten-Block angehängt:
+For `index.html` only, a JSON metadata block is appended:
```html
<script id="stili-json" type="application/json">
{
- "project": "Projektname",
+ "project": "Project Name",
"groupId": "de.juplo",
- "artifactId": "hibernate-maven-plugin",
- "version": "2.1.1",
+ "artifactId": "my-artifact",
+ "version": "1.0.0",
"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.
+### JSON `pages` Array
-Jeder Eintrag:
+Every entry in `pages` represents one page in the site, in menu order. The position in the array serves as the `weight` for navigation sorting.
```json
{
}
```
-- `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/"`
+| Field | Description |
+|---|---|
+| `href` | Filename relative to the site root |
+| `childs` | Direct children in the menu tree (their `href` values) |
+| `crumbs` | Ancestors from the root, excluding `index.html` |
+| `path` | Ancestors as a directory path: `crumbs` with `.html` replaced by `/` |
-### Seitentypen im Maven-Output
+### Page Types
-| Typ | Beispiel | Erkennung |
+| Type | Example | Detection |
|---|---|---|
| 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 |
+| Section node (has children) | `project-reports.html` | `childs.length > 0` |
+| Leaf page | `configuration.html` | `childs.length == 0` |
+| Generated content | `apidocs/`, `xref/` | Directory, not an HTML file |
-Generierter Content (JavaDocs, Xref etc.) erscheint als Unterverzeichnis im Maven-Site-Output und hat einen Eintrag in `pages` mit `href` wie `apidocs/index.html`.
+Generated content (Javadoc, Xref etc.) appears as a subdirectory in the Maven site output and has an entry in `pages` with an `href` like `apidocs/index.html`.
-### Extraktion des Body-Inhalts
+### Body Extraction
-Aus den HTML-Dateien wird der Body so extrahiert:
+The HTML body is extracted from each file with:
```bash
sed -n '/<script id="stili-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="stili-title">...`)
+`sed` outputs all lines before the JSON block (or the entire file if there is no JSON block); `tail -n +2` strips the `<h1 id="stili-title">` first line.
----
+## Import Scripts
-## Import-Skripte
-
-Die Skin liefert Import-Skripte als Maven-Resources 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]
-```
+The skin ships both import scripts as Maven resources. They are copied into `target/site/` by `mvn site` and run from there.
-Jedes Skript liest den `stili-json`-Block aus `index.html`, extrahiert daraus Metadaten und Seitenstruktur und überträgt dann jeden HTML-Body in das Ziel-System — mit generator-spezifischem Frontmatter und Routing-Dateien.
+### Common Parameters
-### Gemeinsame Parameter (beide Skripte)
-
-| Parameter | Bedeutung |
+| Parameter | Description |
|---|---|
-| `--base <path>` | URL-Präfix vor `/<project>/`. Ohne `--base`: Projekt direkt unter Root. |
-| `--project <name>` | Überschreibt den Projektnamen (Default: `artifactId` aus Metadaten). |
-| `--current [<url>]` | Version als aktuelle Hauptversion markieren (Default-Modus). |
-| `--archived [<url>]` | Version als archivierte Nebenversion markieren. |
-| `--canonical <url>` | URL-Basis der kanonischen Version (nur mit `--archived`; Default: `<base>/<project>`). |
+| `--base <path>` | URL prefix before `/<project>/`. Omit for root-level projects. |
+| `--project <name>` | Overrides the project name (default: `artifactId` from metadata). |
+| `--current [<url>]` | Marks this version as the current primary version (default mode). |
+| `--archived [<url>]` | Marks this version as an archived secondary version. |
+| `--canonical <url>` | Canonical version URL base (only with `--archived`). |
-**URL-Normalisierung** (identisch in beiden Skripten):
+### `import-in-hugo.sh` — Import into Hugo
-```bash
-BASE="${2%/}"; BASE="${BASE#/}"; [[ -n "$BASE" ]] && BASE="/$BASE"
-URL_BASE="${2%%/}"; URL_BASE="/${URL_BASE##/}"
-```
+- HTML pages → `content/$BASE/$PROJECT/$VERSION/` with YAML frontmatter (including `outputs` and `layout`)
+- Generated content → `static/$URL_BASE/`
+- Menu entries for generated directories get a Hugo content page with a JS redirect
+- `<pre>` blocks are converted to Hugo `{{< highlight >}}` shortcodes via `perl`
-### `import-in-hugo.sh` — Import in Hugo
+### `import-in-astro.sh` — Import into Astro
-Importiert Maven-Site-Output in ein Hugo-Projekt:
+- HTML pages → `src/content/projects/$PROJECT/$VERSION/` with YAML frontmatter
+- Routing files → `src/pages$BASE/$PROJECT/` (current) or `src/pages$BASE/$PROJECT/$VERSION/` (archived)
+- Generated content → `public/projects/$PROJECT/$VERSION/`
+- Relative links to generated directories (`apidocs/`, `xref/` etc.) are rewritten to absolute URLs
-- 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
+#### Page Structure in Astro Projects
-### `import-in-astro.sh` — Import in Astro
+Section nodes (pages with children) become `_index.html` in a subdirectory:
-Importiert Maven-Site-Output in ein Astro-Projekt:
+| Maven output | Content path | URL (current) |
+|---|---|---|
+| `index.html` | `_index.html` | `/<project>/` |
+| `project-reports.html` (has children) | `project-reports/_index.html` | `/<project>/project-reports.html` |
+| `plugin-info.html` (has children) | `project-reports/plugin-info/_index.html` | `/<project>/plugin-info.html` |
+| `create-mojo.html` (leaf) | `project-reports/plugin-info/create-mojo.html` | `/<project>/create-mojo.html` |
-- HTML-Seiten → `src/content/projects/$PROJECT/$VERSION/` (YAML-Frontmatter ohne Hugo-Felder)
-- Routing-Dateien → `src/pages$BASE/$PROJECT/` (current) oder `src/pages$BASE/$PROJECT/$VERSION/` (archived)
-- Generierter Content → `public/projects/$PROJECT/$VERSION/` (immer fix, unabhängig von `--base`)
-- 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 (`$BASE/<project>/`) oder der archivierten URL (`$BASE/X/Y/`) ausgeliefert wird
-- Die Option `--base` ermöglicht ein URL-Präfix-Verzeichnis (z.B. `--base /projects`); Routing-Tiefe wird dynamisch aus der resultierenden URL-Tiefe berechnet
+URLs are always **flat** (no URL nesting), mirroring Maven's own flat site structure.
-#### Seitenstruktur im Astro-Projekt
+## Building
-Section-Nodes (Seiten mit Kinder-Einträgen) werden zu `_index.html` in einem Unterverzeichnis:
+The project uses the [Maven Wrapper](https://maven.apache.org/wrapper/) — no local Maven installation needed:
-| 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` |
+```bash
+./mvnw clean site
+```
-URLs sind immer **flach** (kein URL-Nesting entsprechend der Content-Hierarchie) — spiegelt Mavens eigene flache Site-Struktur wider.
+## Documentation
-#### Bekannte generierte Verzeichnisse
+Full documentation including the architecture reference and import script details is available at <https://juplo.github.io/maven-stili-skin/>.
-Die folgenden Verzeichnisse werden vom Astro-Projekt als Nav-Einträge erkannt (definiert in `src/lib/projects.ts`, `GENERATED_DOC_NAMES`):
+## License
-| Verzeichnis | Nav-Bezeichnung |
-|---|---|
-| `apidocs/` | JavaDocs |
-| `testapidocs/` | Test JavaDocs |
-| `xref/` | Source Xref |
-| `xref-test/` | Test Source Xref |
+Maven StILi Skin is licensed under the [GNU Lesser General Public License, Version 3.0](LICENSE).
projects / maven-thymeleaf-skin / commitdiff