From b9909f199b488103143b27c502ac42553ca00186 Mon Sep 17 00:00:00 2001
From: Kai Moritz <kai.milan.moritz@googlemail.com>
Date: Fri, 16 Oct 2026 11:47:54 +0200
Subject: [PATCH] =?utf8?q?Dokumentation=20=C3=BCberarbeitet?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

---
 pom.xml                                  |  14 +++
 src/main/resources/img/claude.svg        |  43 +++++++
 src/site/markdown/getting-started.md     |  81 +++++++++++++
 src/site/markdown/import-in-astro.md     |  11 +-
 src/site/markdown/import-in-hugo.md      |  11 +-
 src/site/markdown/supported-platforms.md | 147 +++++++++++++++++++++++
 src/site/site.xml                        |   8 +-
 7 files changed, 300 insertions(+), 15 deletions(-)
 create mode 100644 src/main/resources/img/claude.svg
 create mode 100644 src/site/markdown/getting-started.md
 create mode 100644 src/site/markdown/supported-platforms.md

diff --git a/pom.xml b/pom.xml
index db2ef22..73204d4 100644
--- a/pom.xml
+++ b/pom.xml
@@ -28,6 +28,20 @@
       <id>kai</id>
       <name>Kai Moritz</name>
       <email>kai@juplo.de</email>
+      <roles>
+        <role>architect</role>
+        <role>developer</role>
+      </roles>
+    </developer>
+    <developer>
+      <id>claude</id>
+      <name>Claude Code - Sonnet 4.6</name>
+      <roles>
+        <role>developer</role>
+      </roles>
+      <properties>
+        <picUrl>img/claude.svg</picUrl>
+      </properties>
     </developer>
   </developers>
 
diff --git a/src/main/resources/img/claude.svg b/src/main/resources/img/claude.svg
new file mode 100644
index 0000000..89db07a
--- /dev/null
+++ b/src/main/resources/img/claude.svg
@@ -0,0 +1,43 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!-- Created with Inkscape (http://www.inkscape.org/) -->
+
+<svg
+   width="27.51667mm"
+   height="17.19792mm"
+   viewBox="0 0 27.51667 17.19792"
+   version="1.1"
+   id="svg5"
+   xml:space="preserve"
+   inkscape:version="1.2.2 (b0a8486541, 2022-12-01)"
+   sodipodi:docname="claude.svg"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:svg="http://www.w3.org/2000/svg"><sodipodi:namedview
+     id="namedview7"
+     pagecolor="#ffffff"
+     bordercolor="#000000"
+     borderopacity="0"
+     inkscape:showpageshadow="2"
+     inkscape:pageopacity="0.0"
+     inkscape:pagecheckerboard="true"
+     inkscape:deskcolor="#000000"
+     inkscape:document-units="mm"
+     showgrid="false"
+     inkscape:zoom="1.3986392"
+     inkscape:cx="-97.594864"
+     inkscape:cy="167.66297"
+     inkscape:window-width="1920"
+     inkscape:window-height="1011"
+     inkscape:window-x="0"
+     inkscape:window-y="0"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="layer1" /><defs
+     id="defs2" /><g
+     inkscape:label="Ebene 1"
+     inkscape:groupmode="layer"
+     id="layer1"
+     transform="translate(-116.74378,-104.81683)"><path
+       style="fill:#d78787;fill-opacity:1;stroke-width:0.264583"
+       d="m 122.03545,120.29496 v -1.71979 h -0.92604 -0.92604 v -1.71979 -1.7198 h -1.7198 -1.71979 v -1.71979 -1.71979 h 1.71979 1.7198 v -3.43958 -3.43959 h 10.31874 10.31875 v 3.43959 3.43958 h 1.71979 1.7198 v 1.71979 1.71979 h -1.7198 -1.71979 v 1.7198 1.71979 h -0.79375 -0.79375 v 1.71979 1.71979 h -0.92604 -0.92604 v -1.71979 -1.71979 h -0.79375 -0.79375 v 1.71979 1.71979 h -0.92604 -0.92604 v -1.71979 -1.71979 h -3.43959 -3.43958 v 1.71979 1.71979 h -0.79375 -0.79375 v -1.71979 -1.71979 h -0.92604 -0.92604 v 1.71979 1.71979 h -0.79375 -0.79375 z m 3.43958,-10.31875 v -1.71979 h -0.92604 -0.92604 v 1.71979 1.71979 h 0.92604 0.92604 z m 11.90625,0 v -1.71979 h -0.79375 -0.79375 v 1.71979 1.71979 h 0.79375 0.79375 z"
+       id="path304" /></g></svg>
diff --git a/src/site/markdown/getting-started.md b/src/site/markdown/getting-started.md
new file mode 100644
index 0000000..6ce7805
--- /dev/null
+++ b/src/site/markdown/getting-started.md
@@ -0,0 +1,81 @@
+# Getting Started
+
+The skin generates the documentation in a comman format, that includes meta-data for each generated page.
+
+The generated documents can be imported into a frontend project afterwards with the help of the included **import scripts**:
+
+Currently, only two frontend frameworks are supported:
+
+- **Astro**: `import-in-astro.sh`
+- **Hugo**: `import-in-hugo.sh`
+
+These scripts have to be called with the Bash-Shell explicitly.
+
+## Prerequisites
+
+- `bash`
+- `jq` (JSON processor)
+- `perl` with `HTML::Entities` module (for `<pre>` block conversion)
+
+## Usage example for Astro
+### Current version
+
+To import the current release directly under the site root, call the
+generated script from the root of your project with the path to the
+frontend-project, where the documentation should be copied to:
+
+```
+bash target/site/import-in-astro.sh \
+    ../path/to/frontend-project
+```
+
+### Archived version
+
+Import an archived version:
+
+```
+bash target/site/import-in-astro.sh \
+    ../path/to/frontend-project \
+    --archived
+```
+
+### Publish archived versions in the subfolder `/projects/`
+
+Import the current release directly under the site root as above:
+
+```
+bash target/site/import-in-astro.sh \
+    ../path/to/frontend-project
+```
+
+Import the archived version under `/projects/<artifact-id>/<version>`:
+
+```
+bash target/site/import-in-astro.sh \
+    ../path/to/frontend-project \
+    --base projects \
+    --archived \
+    --canonical <artifact-id>
+```
+
+## Common parameters of all scripts
+
+| Parameter | Description |
+|---|---|
+| `<PROJECT_ROOT>` | Path to the project root (required). |
+| `--base <path>` | URL and content path prefix. The project name and version are always appended. Default: none (project at root). |
+| `--project <name>` | Overrides the project name derived from `artifactId`. |
+| `--current [<url>]` | *(Default)* Marks this version as the current (visible) release. If `<url>` is given, it overrides the computed URL base. |
+| `--archived [<url>]` | Marks this version as archived. `params.canonical` points to the corresponding current-version page. If `<url>` is given, it overrides the computed URL base. |
+| `--canonical <url>` | Explicitly sets the canonical URL base. Only valid with `--archived`. Default: `<base>/<project>`. |
+
+Only one of `--current` and `--archived` may be specified.
+
+## URL Defaults
+
+| Mode | URL Base |
+|---|---|
+| `--current`, no `--base` | `/<artifact-id>/` |
+| `--current --base /path` | `/path/artifact-id>/` |
+| `--archived`, no `--base` | `/<project>/<version>/` |
+| `--archived --base /path` | `/path/<artifact-id>/<version>/` |
diff --git a/src/site/markdown/import-in-astro.md b/src/site/markdown/import-in-astro.md
index c170468..078dcd8 100644
--- a/src/site/markdown/import-in-astro.md
+++ b/src/site/markdown/import-in-astro.md
@@ -12,8 +12,7 @@
 Run the script from the Maven site output directory (`target/site/`):
 
 ```
-cd target/site
-./import-in-astro.sh <ASTRO_ROOT> [OPTIONS]
+bash target/site/import-in-astro.sh <ASTRO_ROOT> [OPTIONS]
 ```
 
 The script checks for `package.json` in `<ASTRO_ROOT>` to verify that the path points to an Astro project.
@@ -114,15 +113,15 @@ The consuming Astro project does not configure `@astrojs/sitemap`, so no automat
 Import the current release directly under the site root:
 
 ```
-cd target/site
-./import-in-astro.sh /path/to/astro-project
+bash target/site/import-in-astro.sh \
+    /path/to/astro-project
 ```
 
 Import an archived version under `/projects/`:
 
 ```
-cd target/site
-./import-in-astro.sh /path/to/astro-project \
+bash target/site/import-in-astro.sh \
+    /path/to/astro-project \
     --base /projects \
     --archived \
     --canonical /my-project
diff --git a/src/site/markdown/import-in-hugo.md b/src/site/markdown/import-in-hugo.md
index 3c41e90..2766423 100644
--- a/src/site/markdown/import-in-hugo.md
+++ b/src/site/markdown/import-in-hugo.md
@@ -13,8 +13,7 @@
 Run the script from the Maven site output directory (`target/site/`):
 
 ```
-cd target/site
-./import-in-hugo.sh <HUGO_ROOT> [OPTIONS]
+bash target/site/import-in-hugo.sh <HUGO_ROOT> [OPTIONS]
 ```
 
 ## Parameters
@@ -72,15 +71,15 @@ For each directory that also has a `pages` entry in `stili-json`, a redirect pag
 Import the current release directly under the site root:
 
 ```
-cd target/site
-./import-in-hugo.sh /path/to/hugo-project
+bash target/site/import-in-hugo.sh \
+    /path/to/hugo-project
 ```
 
 Import an archived version under `/projects/`:
 
 ```
-cd target/site
-./import-in-hugo.sh /path/to/hugo-project \
+bash target/site/import-in-hugo.sh \
+    /path/to/hugo-project \
     --base /projects \
     --archived \
     --canonical /my-project
diff --git a/src/site/markdown/supported-platforms.md b/src/site/markdown/supported-platforms.md
new file mode 100644
index 0000000..7829b9a
--- /dev/null
+++ b/src/site/markdown/supported-platforms.md
@@ -0,0 +1,147 @@
+# Supported Platforms
+
+## Astro
+
+See:
+
+```
+bash target/site/import-in-astro.sh --help
+```
+
+[Detailed information](import-in-astro.html)
+
+## Hugo
+
+See:
+
+```
+bash target/site/import-in-hugo.sh --help
+```
+
+[Detailed information](import-in-hugo.html)
+
+## Add Your Favourite Platform
+
+You are welcome, to add support for your prefered platform.
+
+To get started, just take a look at the static HTML, that is generated by this Maven Skin.
+
+## `<h1 id="stili-title">`
+The `<h1>`-tag with the id `stili-title` contains the title of the documentation page.
+
+## `<div id="stili-body">`
+The `<div>`-tag with the id `stili-body` contains the content of the documentation page.
+
+## `<script id="stili-json">`
+The `<script>`-tag with the id `stili-body` contains meta-information of the _complete_ site-structure, that is collected by the Maven StILi Skin during the generation of the documentation.
+
+_Note:_ Each page contains the complete meta information for the generated documentation. Hence, you can grab the whole picture from the `<script id="stili-json">` of any page, that is generated based on one of the sources, that are formatted by the [Apache Maven Site Plugin](https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html).
+
+Example JSON (as generated for the documentation of this skin): 
+
+```json
+{
+  "project": "Maven StILi Skin",
+  "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.",
+  "groupId": "de.juplo.maven",
+  "artifactId": "maven-stili-skin",
+  "version": "1.0.0",
+  "generator": "Apache Maven Doxia Site Renderer 1.11.1",
+  "generated": "2026-10-17T12:46:33Z",
+  "weight": 100,
+  "pages": [
+    {
+      "name": "Overview",
+      "href": "index.html",
+      "childs": [
+        "project-info.html",
+        "getting-started.html",
+        "architecture.html",
+        "supported-platforms.html"      ],
+      "crumbs": [      ],
+      "path": ""
+    },
+    {
+      "name": "Project Information",
+      "href": "project-info.html",
+      "childs": [
+        "summary.html",
+        "licenses.html",
+        "team.html",
+        "plugins.html"      ],
+      "crumbs": [      ],
+      "path": ""
+    },
+    {
+      "name": "Summary",
+      "href": "summary.html",
+      "childs": [      ],
+      "crumbs": [
+        "project-info.html"      ],
+      "path": "project-info/"
+    },
+    {
+      "name": "Licenses",
+      "href": "licenses.html",
+      "childs": [      ],
+      "crumbs": [
+        "project-info.html"      ],
+      "path": "project-info/"
+    },
+    {
+      "name": "Team",
+      "href": "team.html",
+      "childs": [      ],
+      "crumbs": [
+        "project-info.html"      ],
+      "path": "project-info/"
+    },
+    {
+      "name": "Plugins",
+      "href": "plugins.html",
+      "childs": [      ],
+      "crumbs": [
+        "project-info.html"      ],
+      "path": "project-info/"
+    },
+    {
+      "name": "Getting Started",
+      "href": "getting-started.html",
+      "childs": [      ],
+      "crumbs": [      ],
+      "path": ""
+    },
+    {
+      "name": "Architecture",
+      "href": "architecture.html",
+      "childs": [      ],
+      "crumbs": [      ],
+      "path": ""
+    },
+    {
+      "name": "Supported Platforms",
+      "href": "supported-platforms.html",
+      "childs": [
+        "import-in-hugo.html",
+        "import-in-astro.html"      ],
+      "crumbs": [      ],
+      "path": ""
+    },
+    {
+      "name": "Hugo",
+      "href": "import-in-hugo.html",
+      "childs": [      ],
+      "crumbs": [
+        "supported-platforms.html"      ],
+      "path": "supported-platforms/"
+    },
+    {
+      "name": "Astro",
+      "href": "import-in-astro.html",
+      "childs": [      ],
+      "crumbs": [
+        "supported-platforms.html"      ],
+      "path": "supported-platforms/"
+    }  ]
+}
+```
diff --git a/src/site/site.xml b/src/site/site.xml
index 0268529..a1da708 100644
--- a/src/site/site.xml
+++ b/src/site/site.xml
@@ -20,10 +20,11 @@
 
   <body>
     <menu name="StILi">
-      <item name="Overview"     href="index.html"/>
+      <item name="Overview" href="index.html"/>
+      <item name="Getting Started" href="getting-started.html"/>
       <item name="Architecture" href="architecture.html"/>
-      <item name="Import Scripts">
-        <item name="Hugo"  href="import-in-hugo.html"/>
+      <item name="Supported Platforms" href="supported-platforms.html">
+        <item name="Hugo" href="import-in-hugo.html"/>
         <item name="Astro" href="import-in-astro.html"/>
       </item>
     </menu>
@@ -32,6 +33,7 @@
 
   <custom>
     <menuName>StILi</menuName>
+    <weight>100</weight>
   </custom>
 
 </project>
-- 
2.39.5