From ffef3352994853d17b5b183e54e296c409014097 Mon Sep 17 00:00:00 2001
From: Kai Moritz <kai@juplo.de>
Date: Sun, 12 Jul 2026 11:17:38 +0200
Subject: [PATCH] =?utf8?q?Dokumentation=20=C3=BCberarbeitet=20/=20korrigie?=
 =?utf8?q?rt?=
MIME-Version: 1.0
Content-Type: text/plain; charset=utf8
Content-Transfer-Encoding: 8bit

---
 src/site/markdown/architecture.md | 25 +++++++++++++------------
 src/site/markdown/index.md        |  6 +++---
 2 files changed, 16 insertions(+), 15 deletions(-)

diff --git a/src/site/markdown/architecture.md b/src/site/markdown/architecture.md
index ee42fcb..7fb6ee8 100644
--- a/src/site/markdown/architecture.md
+++ b/src/site/markdown/architecture.md
@@ -11,7 +11,7 @@ The Velocity template `src/main/resources/META-INF/maven/site.vm` is the core of
 </div>
 ```
 
-**For `index.html` only**, a JSON metadata block is appended after the body:
+A JSON metadata block is appended after the body:
 
 ```html
 <script id="stili-json" type="application/json">
@@ -25,7 +25,7 @@ The Velocity template `src/main/resources/META-INF/maven/site.vm` is the core of
 </script>
 ```
 
-This block is the machine-readable interface between StILi and the import scripts. It appears only in `index.html` so that the import scripts have a single, predictable location for the full site metadata.
+This block is the machine-readable interface between StILi and the import scripts.
 
 ## The `stili-json` Format
 
@@ -43,17 +43,18 @@ The top-level fields mirror the Maven project coordinates:
 
 ### The `pages` Array
 
-The `pages` array contains every page of the Maven site in the order they appear in the configured navigation menu. Array position serves as the `weight` for navigation sorting in the target system.
+The `pages` array contains every page of the Maven site in the order they appear in the configured navigation menu. The array position serves as the `weight` for sorting of the entries in the navigation of the target system.
 
-Each entry:
+Each entry looks like the following example:
 
 ```json
 {
-  "name": "Project Reports",
-  "href": "project-reports.html",
-  "childs": ["plugin-info.html"],
-  "crumbs": [],
-  "path": ""
+  "name": "Plugins",
+  "href": "plugins.html",
+  "childs": [      ],
+  "crumbs": [
+    "project-info.html"      ],
+  "path": "project-info/"
 }
 ```
 
@@ -62,8 +63,8 @@ Each entry:
 | `name` | Display name of the page |
 | `href` | Filename relative to the site root (e.g. `project-reports.html`; for generated directories e.g. `apidocs/index.html`) |
 | `childs` | Direct children in the menu tree (their `href` values) |
-| `crumbs` | Ancestor pages from the root, excluding `index.html` (e.g. `["project-reports.html"]`) |
-| `path` | Ancestors as a directory path — `crumbs` with `.html` replaced by `/` (e.g. `"project-reports/"`) |
+| `crumbs` | Ancestor pages of the page (their `href` values), beginning at the root of the project, but excluding `index.html` |
+| `path` | Ancestors of the page as a directory path — that is, the entries of `crumbs` concatenated and with `.html` replaced by `/` |
 
 ## Page Types
 
@@ -78,7 +79,7 @@ Generated content (JavaDocs, cross-references, etc.) appears as a subdirectory i
 
 ## Body Extraction
 
-Import scripts extract the page body from each HTML file using this pattern:
+Import scripts can extract the page body from each HTML file using a pattern like this:
 
 ```bash
 sed -n '/<script id="stili-json" type="application\/json">/q;p' "$SOURCE" \
diff --git a/src/site/markdown/index.md b/src/site/markdown/index.md
index 3a767cf..9da8b9e 100644
--- a/src/site/markdown/index.md
+++ b/src/site/markdown/index.md
@@ -11,7 +11,7 @@ ${project.description}
 - **Import**: The mechanism is a set of import scripts that transfer the generated Maven output into the target system.
 - **Site**: The source is Maven Doxia site output.
 
-The name also deliberately echoes the German and Italian word for *style* (*Stil* / *stile*) — a nod to the fact that StILi liberates Maven site content in a stylish way.
+The name also deliberately echoes the German word for *style* (*Stil*) — a nod to the fact that StILi liberates the content of Maven websites so it can be adapted to match the style of the site where the project is hosted.
 
 ## Quick Start
 
@@ -35,7 +35,7 @@ The `<menuName>` custom element tells StILi which menu in `site.xml` is the prim
 
 After running `mvn site`, the generated output in `target/site/` contains the regular HTML files plus the import scripts. Run the appropriate import script from that directory:
 
-```
+```bash
 cd target/site
 ./import-in-astro.sh /path/to/your/astro-project --base /projects --archived
 ```
@@ -53,7 +53,7 @@ Generator-specific logic lives in import scripts, which the skin ships as Maven
 | `import-in-hugo.sh` | Hugo |
 | `import-in-astro.sh` | Astro |
 
-Anyone who wants to use StILi with a different generator writes a new import script. Contributions are welcome.
+Anyone who wants to use StILi with a different generator can simply write a new import script, that targets this generator: Contributions are welcome.
 
 ## License
 
-- 
2.39.5