From: Kai Moritz <kai.milan.moritz@googlemail.com>
Date: Wed, 17 Jun 2026 16:59:51 +0000 (+0000)
Subject: Rename sili → StILi: update all identifiers and documentation
X-Git-Url: http://juplo.de/gitweb/?a=commitdiff_plain;h=67aa5b86a48f2498d8b51018dace0d4e6446ca42;p=maven-thymeleaf-skin

Rename sili → StILi: update all identifiers and documentation

The project identifier is renamed from the informal "sili" to "StILi"
((St)atic (I)mport site (Li)berator), which makes the purpose explicit
and sounds like the German/Italian word for "style".

- pom.xml: artifactId maven-siteliberator-skin → maven-stili-skin,
  updated name, description, and SCM URLs
- site.vm: HTML IDs sili-title/sili-body/sili-json → stili-*
- import scripts: stili-json pattern, mention StILi skin in usage text,
  add --base option to import-in-astro.sh (general-purpose support)
- CLAUDE.md: rewritten with name origin, community architecture model,
  and updated stili-* references throughout

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---

diff --git a/CLAUDE.md b/CLAUDE.md
index 753baa0..39f210c 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -14,17 +14,42 @@ Diese Datei enthält Anweisungen für Claude Code (claude.ai/code) beim Arbeiten
 
 ---
 
-## Zweck
+## Was ist StILi?
 
-`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.
+**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
-<h1 id="sili-title">Seitentitel</h1>
-<div id="sili-body">
+<h1 id="stili-title">Seitentitel</h1>
+<div id="stili-body">
   $bodyContent
 </div>
 ```
@@ -32,7 +57,7 @@ Das Velocity-Template `src/main/resources/META-INF/maven/site.vm` ist das Herzst
 **Nur für `index.html`** wird zusätzlich ein JSON-Metadaten-Block angehängt:
 
 ```html
-<script id="sili-json" type="application/json">
+<script id="stili-json" type="application/json">
 {
   "project": "Projektname",
   "groupId": "de.juplo",
@@ -80,22 +105,43 @@ Generierter Content (JavaDocs, Xref etc.) erscheint als Unterverzeichnis im Mave
 Aus den HTML-Dateien wird der Body so extrahiert:
 
 ```bash
-sed -n '/<script id="sili-json" type="application\/json">/q;p' "$SOURCE" \
+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="sili-title">...`)
+- `tail -n +2` entfernt die erste Zeile (`<h1 id="stili-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:
+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]
 ```
 
+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.
+
+### Gemeinsame Parameter (beide Skripte)
+
+| Parameter | Bedeutung |
+|---|---|
+| `--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>`). |
+
+**URL-Normalisierung** (identisch in beiden Skripten):
+
+```bash
+BASE="${2%/}"; BASE="${BASE#/}"; [[ -n "$BASE" ]] && BASE="/$BASE"
+URL_BASE="${2%%/}"; URL_BASE="/${URL_BASE##/}"
+```
+
 ### `import-in-hugo.sh` — Import in Hugo
 
 Importiert Maven-Site-Output in ein Hugo-Projekt:
@@ -105,16 +151,15 @@ Importiert Maven-Site-Output in ein Hugo-Projekt:
 - 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):
+Importiert Maven-Site-Output in ein Astro-Projekt:
 
 - 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
+- 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
 
 #### Seitenstruktur im Astro-Projekt
 
diff --git a/pom.xml b/pom.xml
index 7ba61be..e2961bd 100644
--- a/pom.xml
+++ b/pom.xml
@@ -9,17 +9,17 @@
   </parent>
 
   <groupId>de.juplo.maven</groupId>
-  <artifactId>maven-siteliberator-skin</artifactId>
+  <artifactId>maven-stili-skin</artifactId>
   <version>1.0.0-SNAPSHOT</version>
 
-  <name>Site-Liberator Skin</name>
-  <description>A maven skin, that makes the generated content and its structure accessible for post-processing.</description>
-  <url>http://juplo.de/maven-siteliberator-skin/index.html</url>
+  <name>Maven StILi Skin</name>
+  <description>A Maven Doxia skin that liberates the generated site content and its structure for import into arbitrary static site generators. StILi = (St)atic (I)mport site (Li)berator.</description>
+  <url>http://juplo.de/maven-stili-skin/index.html</url>
 
   <scm>
-    <connection>scm:git:http://juplo.de/git/maven-siteliberator-skin</connection>
-    <developerConnection>scm:git:ssh://juplo.de:/var/lib/git/juplo/maven-siteliberator-skin</developerConnection>
-    <url>http://juplo.de/gitweb/?p=maven-siteliberator-skin;a=summary</url>
+    <connection>scm:git:http://juplo.de/git/maven-stili-skin</connection>
+    <developerConnection>scm:git:ssh://juplo.de:/var/lib/git/juplo/maven-stili-skin</developerConnection>
+    <url>http://juplo.de/gitweb/?p=maven-stili-skin;a=summary</url>
   </scm>
 
   <developers>
diff --git a/src/main/resources/META-INF/maven/site.vm b/src/main/resources/META-INF/maven/site.vm
index 6821e15..6b3e481 100644
--- a/src/main/resources/META-INF/maven/site.vm
+++ b/src/main/resources/META-INF/maven/site.vm
@@ -67,8 +67,8 @@
 #set ( $sinkhole = $pages.get($currentItemHref).put("name", $item.name) )
 #end
 #end
-<h1 id="sili-title">$!{shortTitle}</h1>
-<div id="sili-body">
+<h1 id="stili-title">$!{shortTitle}</h1>
+<div id="stili-body">
 $bodyContent
 </div>
 #if (!$alignedFilePath or $alignedFilePath == 'index.html')
@@ -109,7 +109,7 @@ $bodyContent
 #end
 #end
 #end
-<script id="sili-json" type="application/json">
+<script id="stili-json" type="application/json">
 {
   "project": "$project.name",
 #if ( $project.description )
diff --git a/src/main/resources/import-in-astro.sh b/src/main/resources/import-in-astro.sh
index fad7c75..f0aac3f 100755
--- a/src/main/resources/import-in-astro.sh
+++ b/src/main/resources/import-in-astro.sh
@@ -2,28 +2,31 @@
 set -euo pipefail
 
 USAGE=$(
-  echo "Usage: $0 <ASTRO_ROOT> [--project <name>] [ [--current [<url>]] | [--archived [<url>] [--canonical <url>]] ]";
+  echo "Usage: $0 <ASTRO_ROOT> [--base <path>] [--project <name>] [ [--current [<url>]] | [--archived [<url>] [--canonical <url>]] ]";
   cat << EOF
 
-  Imports a Maven site generated with the sili-skin into an Astro project.
+  Imports a Maven site generated with the StILi skin into an Astro project.
   Run this script from the Maven site output directory (where index.html lives).
 
+--base      : URL and routing path prefix (default: none, project at root).
+              The project name is always appended; for --archived the version
+              is appended as well.
 --project   : Overrides the project name used for URL and directory paths
               (Default: artifactId from the Maven project metadata).
 --current   : [DEFAULT]
               Marks this version as the current (visible) release.
-              Content URL: /<project>/page.html, params.current=true
-              Routing:     src/pages/<project>/
+              Content URL: <base>/<project>/page.html, params.current=true
+              Routing:     src/pages/<base>/<project>/
               If <url> is given, it overrides the URL base.
               Only one of --current and --archived can be used!
 --archived  : Marks this version as archived (not visible by default).
-              Content URL: /projects/<project>/<version>/page.html, params.current=false
-              Routing:     src/pages/projects/<project>/<version>/
+              Content URL: <base>/<project>/<version>/page.html, params.current=false
+              Routing:     src/pages/<base>/<project>/<version>/
               params.canonical points to the corresponding current-version page.
               If <url> is given, it overrides the URL base.
               Only one of --current and --archived can be used!
 --canonical : Explicitly sets the canonical URL base for --archived mode.
-              Default: /<project>
+              Default: <base>/<project>
               Only valid with --archived.
 EOF
 )
@@ -38,6 +41,7 @@ SCRIPT_DIR=$( cd -- "$( dirname -- "${BASH_SOURCE[0]}" )" &> /dev/null && pwd )
 ASTRO_ROOT="${1%%/}"
 shift
 
+BASE=""
 PROJECT=""
 CURRENT=0
 ARCHIVED=0
@@ -53,6 +57,12 @@ fi
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
+    --base)
+      if [[ $# -lt 2 ]]; then echo "ERROR -- Parameter for --base is missing!"; exit 1; fi
+      BASE="${2%/}"; BASE="${BASE#/}"
+      [[ -n "$BASE" ]] && BASE="/$BASE"
+      shift 2
+      ;;
     --project)
       if [[ $# -lt 2 ]]; then echo "ERROR -- Parameter for --project is missing!"; exit 1; fi
       PROJECT="${2%%/}"; PROJECT="${PROJECT##/}"; shift 2
@@ -96,7 +106,7 @@ if [[ "$CURRENT" -eq 0 && "$ARCHIVED" -eq 0 ]]; then
 fi
 [[ "$CURRENT" -eq 1 ]] && CURRENT_BOOL="true" || CURRENT_BOOL="false"
 
-JSON=$(sed -n '/<script id="sili-json" type="application\/json">/,/<\/script>/p' "${SCRIPT_DIR}/index.html" | sed '1d;$d')
+JSON=$(sed -n '/<script id="stili-json" type="application\/json">/,/<\/script>/p' "${SCRIPT_DIR}/index.html" | sed '1d;$d')
 echo "$JSON" | jq -C .
 
 [[ -z "$PROJECT" ]] && PROJECT=$(echo "$JSON" | jq -r '.artifactId')
@@ -105,24 +115,23 @@ VERSION=$(echo "$JSON" | jq -r '.version')
 if [[ -n "$URL_BASE" ]]; then
   URL_BASE="${URL_BASE%/}"
 elif [[ "$CURRENT_BOOL" == "true" ]]; then
-  URL_BASE="/$PROJECT"
+  URL_BASE="$BASE/$PROJECT"
 else
-  URL_BASE="/projects/$PROJECT/$VERSION"
+  URL_BASE="$BASE/$PROJECT/$VERSION"
 fi
 
-[[ -z "$CANONICAL" ]] && CANONICAL="/$PROJECT"
+[[ -z "$CANONICAL" ]] && CANONICAL="$BASE/$PROJECT"
 CANONICAL="${CANONICAL%/}"
 
 CONTENT_BASE="$ASTRO_ROOT/src/content/projects/$PROJECT/$VERSION"
 PUBLIC_BASE="$ASTRO_ROOT/public/projects/$PROJECT/$VERSION"
 
-if [[ "$CURRENT_BOOL" == "true" ]]; then
-  PAGES_BASE="$ASTRO_ROOT/src/pages/$PROJECT"
-  IMPORT_DEPTH="../../"
-else
-  PAGES_BASE="$ASTRO_ROOT/src/pages/projects/$PROJECT/$VERSION"
-  IMPORT_DEPTH="../../../../"
-fi
+# Routing files mirror the URL structure: src/pages<URL_BASE>/
+PAGES_BASE="$ASTRO_ROOT/src/pages${URL_BASE}"
+
+# Import depth = number of path segments in URL_BASE + 1 (to reach src/ from pages/)
+SLASH_COUNT=$(tr -dc '/' <<< "${URL_BASE#/}" | wc -c)
+IMPORT_DEPTH=$(printf '../%.0s' $(seq 1 $((SLASH_COUNT + 2))))
 
 echo ""
 echo "Project:   $PROJECT"
@@ -181,7 +190,7 @@ for SOURCE in $(find "$SCRIPT_DIR" -maxdepth 1 -mindepth 1 -type f -name '*.html
     echo "  current: $CURRENT_BOOL"
     [[ "$CURRENT_BOOL" == "false" ]] && echo "  canonical: $CANONICAL_URL"
     echo "---"
-    sed -n '/<script id="sili-json" type="application\/json">/q;p' "$SOURCE" \
+    sed -n '/<script id="stili-json" type="application\/json">/q;p' "$SOURCE" \
       | tail -n +2
   } > "$CONTENT_TARGET"
 
diff --git a/src/main/resources/import-in-hugo.sh b/src/main/resources/import-in-hugo.sh
index 1540bb2..7b998de 100755
--- a/src/main/resources/import-in-hugo.sh
+++ b/src/main/resources/import-in-hugo.sh
@@ -5,7 +5,7 @@ USAGE=$(
   echo "Usage: $0 <HUGO_ROOT> [--base <path>] [--project <name>] [ [--current [<url>]] | [--archived [<url>] [--canonical <url>]] ]";
   cat << EOF
 
-  Imports a Maven site generated with the sili-skin into a Hugo project.
+  Imports a Maven site generated with the StILi skin into a Hugo project.
   Run this script from the Maven site output directory (where index.html lives).
 
 --base      : URL and content path prefix (default: none, project at root).
@@ -99,7 +99,7 @@ if [[ "$CURRENT" -eq 0 && "$ARCHIVED" -eq 0 ]]; then
 fi
 [[ "$CURRENT" -eq 1 ]] && CURRENT_BOOL="true" || CURRENT_BOOL="false"
 
-JSON=$(sed -n '/<script id="sili-json" type="application\/json">/,/<\/script>/p' "${SCRIPT_DIR}/index.html" | sed '1d;$d')
+JSON=$(sed -n '/<script id="stili-json" type="application\/json">/,/<\/script>/p' "${SCRIPT_DIR}/index.html" | sed '1d;$d')
 echo "$JSON" | jq -C .
 
 [[ -z "$PROJECT" ]] && PROJECT=$(echo "$JSON" | jq -r '.artifactId')
@@ -172,7 +172,7 @@ for SOURCE in $(find "$SCRIPT_DIR" -maxdepth 1 -mindepth 1 -type f -name '*.html
     echo "  current: $CURRENT_BOOL"
     echo "  canonical: $CANONICAL_URL"
     echo "---"
-    sed -n '/<script id="sili-json" type="application\/json">/q;p' "$SOURCE" \
+    sed -n '/<script id="stili-json" type="application\/json">/q;p' "$SOURCE" \
       | tail -n +2 \
       | perl -0777 -MHTML::Entities -pe \
           's#<pre\b[^>]*>(.*?)</pre>#"{{< highlight guess >}}\n".decode_entities($1)."\n{{< /highlight >}}"#gse'