---
-## 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>
```
**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",
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:
- 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
</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>
#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')
#end
#end
#end
-<script id="sili-json" type="application/json">
+<script id="stili-json" type="application/json">
{
"project": "$project.name",
#if ( $project.description )
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
)
ASTRO_ROOT="${1%%/}"
shift
+BASE=""
PROJECT=""
CURRENT=0
ARCHIVED=0
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
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')
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"
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"
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).
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')
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'
projects / maven-thymeleaf-skin / commitdiff