From: Kai Moritz Date: Wed, 17 Jun 2026 19:32:52 +0000 (+0000) Subject: Rewrite README.md for GitHub: English, public-facing documentation X-Git-Url: http://juplo.de/gitweb/?a=commitdiff_plain;h=6a551bc67f256b7ae969c7307d163e42d9611063;p=maven-thymeleaf-skin Rewrite README.md for GitHub: English, public-facing documentation Removes AI working instructions; keeps project documentation (What is StILi, Quick Start, How It Works, Import Scripts, Building). Content is adapted from the former CLAUDE.md and src/site/markdown/index.md. --- diff --git a/README.md b/README.md index 529c0ea..750c103 100644 --- a/README.md +++ b/README.md @@ -1,146 +1,89 @@ -# CLAUDE.md +# Maven StILi Skin -Diese Datei enthält Anweisungen für Claude Code (claude.ai/code) beim Arbeiten mit diesem Repository. +[![License: LGPL v3](https://img.shields.io/badge/License-LGPL_v3-blue.svg)](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=` 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 + + + de.juplo.maven + maven-stili-skin + 1.0.0 + + + Your Main Menu Name + + ... + ``` -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 `` 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 -

Seitentitel

+

Page title

$bodyContent
``` -**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 ``` -### 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 { @@ -152,103 +95,88 @@ Jeder Eintrag: } ``` -- `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 '/