Restructure exampleSite once again, improve sections and flow

exampleSite/assets/icons/apparel.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#1f1f1f"><path d="m240-522-40 22q-14 8-30 4t-24-18L66-654q-8-14-4-30t18-24l230-132h70q9 0 14.5 5.5T400-820v20q0 33 23.5 56.5T480-720q33 0 56.5-23.5T560-800v-20q0-9 5.5-14.5T580-840h70l230 132q14 8 18 24t-4 30l-80 140q-8 14-23.5 17.5T760-501l-40-20v361q0 17-11.5 28.5T680-120H280q-17 0-28.5-11.5T240-160v-362Zm80-134v456h320v-456l124 68 42-70-172-100q-15 51-56.5 84.5T480-640q-56 0-97.5-33.5T326-758L154-658l42 70 124-68Zm160 177Z"/></svg>

exampleSite/assets/icons/rocket.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" height="24px" viewBox="0 -960 960 960" width="24px" fill="#1f1f1f"><path d="m226-559 78 33q14-28 29-54t33-52l-56-11-84 84Zm142 83 114 113q42-16 90-49t90-75q70-70 109.5-155.5T806-800q-72-5-158 34.5T492-656q-42 42-75 90t-49 90Zm155-121.5q0-33.5 23-56.5t57-23q34 0 57 23t23 56.5q0 33.5-23 56.5t-57 23q-34 0-57-23t-23-56.5ZM565-220l84-84-11-56q-26 18-52 32.5T532-299l33 79Zm313-653q19 121-23.5 235.5T708-419l20 99q4 20-2 39t-20 33L538-80l-84-197-171-171-197-84 167-168q14-14 33.5-20t39.5-2l99 20q104-104 218-147t235-24ZM157-321q35-35 85.5-35.5T328-322q35 35 34.5 85.5T327-151q-25 25-83.5 43T82-76q14-103 32-161.5t43-83.5Zm57 56q-10 10-20 36.5T180-175q27-4 53.5-13.5T270-208q12-12 13-29t-11-29q-12-12-29-11.5T214-265Z"/></svg>

exampleSite/content.en/_index.md

@@ -11,7 +11,7 @@ layout: landing
   Hugo-Book theme is designed to be easy to read, write, navigate and maintain.
   It is an attempt to create a sustainable web project.
 
-  {{<button href="/docs/introduction">}}Explore{{</button>}}
+  {{<button href="/docs/getting-started/introduction">}}Explore{{</button>}}
 
 - ```shell
   # TL;DR
@@ -45,13 +45,13 @@ layout: landing
 - {{< card >}}
   ### Shortcodes {anchor=false}
   Pretty good shortcodes are included to enhance content:
-  [Columns](/docs/shortcodes/columns/),
+  [Columns](/docs/content/shortcodes/columns/),
-  [Cards](/docs/shortcodes/experimental/cards/),
+  [Cards](/docs/content/shortcodes/cards/),
-  [Tabs](/docs/shortcodes/tabs/),
+  [Tabs](/docs/content/shortcodes/tabs/),
-  [Images](/docs/shortcodes/experimental/images/),
+  [Images](/docs/content/shortcodes/images/),
-  [Asciinema](/docs/shortcodes/asciinema/),
+  [Asciinema](/docs/content/shortcodes/asciinema/),
-  [KaTex](/docs/shortcodes/katex/),
+  [KaTex](/docs/content/shortcodes/katex/),
-  [Mermaid](/docs/shortcodes/mermaid/) and others.
+  [Mermaid](/docs/content/shortcodes/mermaid/) and others.
   {{< /card >}}
 
 - {{< card >}}

exampleSite/content.en/docs/content/_index.md

@@ -1,55 +1,6 @@
 ---
-weight: 40
 title: Content & Structure
-bookCollapseSection: true
+weight: 20
+bookFlatSection: true
+bookIcon: edit
 ---
-
-# Content Organization
-
-Hugo Book renders pages from a section as a sidebar menu. By default this is the `docs/` directory.
-
-## Example Directory Structure
-
-```
-content/
-├── docs/
-│   ├── _index.md
-│   ├── getting-started.md
-│   ├── guide/
-│   │   ├── _index.md
-│   │   ├── install.md
-│   │   └── configure.md
-│   └── reference/
-│       └── _index.md
-├── posts/
-│   ├── _index.md
-│   └── my-post.md
-└── _index.md
-```
-
-Pages are ordered by `weight` frontmatter, then alphabetically. Section `_index.md` files define the section entry in the menu.
-
-## Changing the Menu Section
-
-By default, pages under `docs/` are rendered as the sidebar menu. Change this with the `BookSection` parameter in [Configuration](/docs/configuration/). Set to `'/'` to render all top-level sections.
-
-## Page Layouts
-
-The theme provides several layouts:
-
-| Layout    | Usage                | Description |
-| --- | --- | --- |
-| (default) | Documentation pages  | Sidebar menu + content + optional ToC |
-| `landing` | `layout: landing`    | Full-width, no sidebar. Used for homepages. |
-| `book`    | `layout: book`       | Single-page view with all subsections listed |
-| `posts`   | Pages under `posts/` | Blog-style with date, tags, pagination |
-
-Set the layout in frontmatter
-
-```yaml {filename=_index.md}
----
-layout: landing
----
-```
-
-See [Pages](/docs/content/pages/) for frontmatter reference and [Menus](/docs/content/menus/) for navigation controls.

exampleSite/content.en/docs/content/blog.md

@@ -1,5 +1,5 @@
 ---
-weight: 3
+weight: 40
 ---
 
 # Blog
@@ -51,4 +51,4 @@ bookPostThumbnail: "cover.*"
 
 ## Date Format
 
-The date display format is configured site-wide via `BookDateFormat`. See [Configuration](/docs/configuration/) for details.
+The date display format is configured site-wide via `BookDateFormat`. See [Configuration](/docs/getting-started/configuration/) for details.

exampleSite/content.en/docs/content/menus.md

@@ -1,5 +1,5 @@
 ---
-weight: 2
+weight: 30
 ---
 
 # Menu System

exampleSite/content.en/docs/content/multilingual.md

@@ -1,6 +1,6 @@
 ---
 title: Multi-Language
-weight: 4
+weight: 50
 ---
 
 # Multi-Language Support

exampleSite/content.en/docs/content/organisation.md

@@ -0,0 +1,54 @@
+---
+title: Organisation
+weight: 10
+---
+
+# Content Organisation
+
+Hugo Book renders pages from a section as a sidebar menu. By default this is the `docs/` directory.
+
+## Example Directory Structure
+
+```
+content/
+├── docs/
+│   ├── _index.md
+│   ├── getting-started.md
+│   ├── guide/
+│   │   ├── _index.md
+│   │   ├── install.md
+│   │   └── configure.md
+│   └── reference/
+│       └── _index.md
+├── posts/
+│   ├── _index.md
+│   └── my-post.md
+└── _index.md
+```
+
+Pages are ordered by `weight` frontmatter, then alphabetically. Section `_index.md` files define the section entry in the menu.
+
+## Changing the Menu Section
+
+By default, pages under `docs/` are rendered as the sidebar menu. Change this with the `BookSection` parameter in [Configuration](/docs/getting-started/configuration/). Set to `'/'` to render all top-level sections.
+
+## Page Layouts
+
+The theme provides several layouts:
+
+| Layout    | Usage                | Description |
+| --- | --- | --- |
+| (default) | Documentation pages  | Sidebar menu + content + optional ToC |
+| `landing` | `layout: landing`    | Full-width, no sidebar. Used for homepages. |
+| `book`    | `layout: book`       | Single-page view with all subsections listed |
+| `posts`   | Pages under `posts/` | Blog-style with date, tags, pagination |
+
+Set the layout in frontmatter
+
+```yaml {filename=_index.md}
+---
+layout: landing
+---
+```
+
+See [Pages](/docs/content/pages/) for frontmatter reference and [Menus](/docs/content/menus/) for navigation controls.

exampleSite/content.en/docs/content/pages.md

@@ -1,5 +1,5 @@
 ---
-weight: 1
+weight: 20
 ---
 
 # Page Frontmatter

exampleSite/content.en/docs/content/shortcodes/cards.md

@@ -1,6 +1,6 @@
 # Cards
 
-Content blocks with optional images and links. Often used with [Columns](/docs/shortcodes/columns) for grid layouts.
+Content blocks with optional images and links. Often used with [Columns](/docs/content/shortcodes/columns) for grid layouts.
 
 ## Syntax
 
@@ -18,7 +18,7 @@ Markdown content
   Cards can display an image above the content.
   {{< /card >}}
 
-- {{< card href="/docs/shortcodes/experimental/cards" >}}
+- {{< card href="/docs/content/shortcodes/cards" >}}
   ### With Link {anchor=false}
   When `href` is set, the entire card becomes clickable.
   {{< /card >}}

exampleSite/content.en/docs/customization/_index.md

@@ -1,139 +1,6 @@
 ---
-weight: 50
+title: Customization
+weight: 30
+bookFlatSection: true
+bookIcon: apparel
 ---
-
-# Customization
-
-Hugo Book can be customized through theming, custom SCSS, 'inject' partials, and file overrides.
-
-## Built-in Themes
-
-Set `BookTheme` in your site config
-
-```toml {filename=hugo.toml}
-[params]
-  BookTheme = 'light'  # or 'dark', 'auto'
-```
-
-| Theme   | Description |
-| --- | --- |
-| `light` | Default. Light background with dark text. |
-| `dark`  | Dark background (Nord palette) with light text. |
-| `auto`  | Switches between light and dark based on OS/browser preference (`prefers-color-scheme`). |
-
-## Plugin Themes
-
-Additional themes are available as SCSS plugins. Import in your `assets/_custom.scss`
-
-```scss
-@import "plugins/themes";
-```
-
-Then set `BookTheme` to one of:
-
-| Theme | Description |
-| --- | --- |
-| `contrast-light`    | High contrast light variant |
-| `contrast-dark`     | High contrast dark variant |
-| `contrast-auto`     | High contrast, auto-switching |
-| `catppuccin-light`  | [Catppuccin](https://catppuccin.com/) Latte palette |
-| `catppuccin-dark`   | Catppuccin Frappe palette |
-| `catppuccin-auto`   | Catppuccin, auto-switching |
-| `ayu-light`         | [Ayu](https://github.com/ayu-theme) light palette |
-| `ayu-dark`          | Ayu mirage dark palette |
-| `ayu-auto`          | Ayu, auto-switching |
-
-## Custom Theme
-
-Define a theme mixin in `assets/_custom.scss`
-
-```scss
-@mixin theme-mytheme {
-  --body-background: #fafafa;
-  --body-font-color: #333;
-  --color-link: #0066cc;
-  --color-visited-link: #6633cc;
-}
-```
-
-Then set `BookTheme = 'mytheme'`. The theme uses `@include theme-{{ .Site.Params.BookTheme }}` to select the mixin at build time.
-
-For auto-switching themes (light/dark based on OS preference), see the `theme-auto` mixin in `assets/_defaults.scss` as a reference.
-
-## CSS Custom Properties
-
-Override CSS custom properties in `_custom.scss` to adjust the current theme. The full set of properties is defined in [`assets/_defaults.scss`](https://github.com/alex-shpak/hugo-book/blob/main/assets/_defaults.scss).
-
-## Custom Styles
-
-The theme includes an empty `assets/_custom.scss` file that is loaded after all theme styles. Create this file in your project's `assets/` directory to add custom CSS without overriding the entire stylesheet.
-
-```scss
-// assets/_custom.scss
-
-.book-page {
-  max-width: 60rem;
-}
-
-.book-menu nav {
-  font-size: 0.9rem;
-}
-```
-
-## SCSS Plugins
-
-The theme ships with optional SCSS plugins. Import them in your `_custom.scss`:
-
-```scss
-@import "plugins/numbered"; /* Automatically number headings in the content area */
-@import "plugins/scrollbars"; /* Style scrollbars in the sidebar and content area */
-```
-
-## SCSS Variables
-
-Layout variables like sidebar width, breakpoints, and padding are defined in [`assets/_defaults.scss`](https://github.com/alex-shpak/hugo-book/blob/main/assets/_defaults.scss). Override them in your `_custom.scss`.
-
-## 'Inject' Partials
-
-The theme provides empty partial templates at key points in the page layout. Override these to inject custom HTML without modifying the base templates.
-
-Create matching files in your project's `layouts/_partials/docs/inject/` directory.
-
-| Partial | Location |
-| --- | --- |
-| `inject/head.html` | Inside `<head>`, e.g. meta tags, stylesheets, scripts |
-| `inject/body.html` | Before `</body>`, e.g. analytics, chat widgets, scripts |
-| `inject/menu-before.html` | Before the sidebar menu |
-| `inject/menu-after.html` | After the sidebar menu |
-| `inject/content-before.html` | Before the page content |
-| `inject/content-after.html` | After the page content |
-| `inject/toc-before.html` | Before the table of contents |
-| `inject/toc-after.html` | After the table of contents |
-| `inject/footer.html` | Inside the page footer |
-
-### Example
-
-To add a Google Analytics script, create `layouts/_partials/docs/inject/head.html`
-
-```html
-{{ with .Site.Params.googleAnalytics }}
-<script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
-{{ end }}
-```
-
-To add a custom banner above every page, create `layouts/_partials/docs/inject/content-before.html`
-
-```html
-<div class="my-banner">
-  This documentation is for version 2.0. See <a href="/v1/">version 1.0 docs</a>.
-</div>
-```
-
-## Override Priority
-
-Hugo's [lookup order](https://gohugo.io/templates/lookup-order/) lets you override any theme file by creating the same file in your project:
-
-- `layouts/`: Override templates and partials
-- `assets/`: Override SCSS and JavaScript
-- `static/`: Override static files (favicon, images)
-- `i18n/`: Override or add translations

exampleSite/content.en/docs/customization/inject-partials.md

@@ -0,0 +1,40 @@
+---
+title: Inject Partials
+weight: 30
+---
+
+# Inject Partials
+
+The theme provides empty partial templates at key points in the page layout. Override these to inject custom HTML without modifying the base templates.
+
+Create matching files in your project's `layouts/_partials/docs/inject/` directory.
+
+| Partial | Location |
+| --- | --- |
+| `inject/head.html` | Inside `<head>`, e.g. meta tags, stylesheets, scripts |
+| `inject/body.html` | Before `</body>`, e.g. analytics, chat widgets, scripts |
+| `inject/menu-before.html` | Before the sidebar menu |
+| `inject/menu-after.html` | After the sidebar menu |
+| `inject/content-before.html` | Before the page content |
+| `inject/content-after.html` | After the page content |
+| `inject/toc-before.html` | Before the table of contents |
+| `inject/toc-after.html` | After the table of contents |
+| `inject/footer.html` | Inside the page footer |
+
+## Example
+
+To add a Google Analytics script, create `layouts/_partials/docs/inject/head.html`
+
+```html
+{{ with .Site.Params.googleAnalytics }}
+<script async src="https://www.googletagmanager.com/gtag/js?id={{ . }}"></script>
+{{ end }}
+```
+
+To add a custom banner above every page, create `layouts/_partials/docs/inject/content-before.html`
+
+```html
+<div class="my-banner">
+  This documentation is for version 2.0. See <a href="/v1/">version 1.0 docs</a>.
+</div>
+```

exampleSite/content.en/docs/customization/styles.md

@@ -0,0 +1,102 @@
+---
+title: Styles
+weight: 20
+---
+
+# Styles
+
+## Built-in Themes
+
+Set `BookTheme` in your site config
+
+```toml {filename=hugo.toml}
+[params]
+  BookTheme = 'light'  # or 'dark', 'auto'
+```
+
+| Theme   | Description |
+| --- | --- |
+| `light` | Default. Light background with dark text. |
+| `dark`  | Dark background (Nord palette) with light text. |
+| `auto`  | Switches between light and dark based on OS/browser preference (`prefers-color-scheme`). |
+
+## Plugin Themes
+
+Additional themes are available as SCSS plugins. Import in your `assets/_custom.scss`
+
+```scss
+@import "plugins/themes";
+```
+
+Then set `BookTheme` to one of:
+
+| Theme | Description |
+| --- | --- |
+| `contrast-light`    | High contrast light variant |
+| `contrast-dark`     | High contrast dark variant |
+| `contrast-auto`     | High contrast, auto-switching |
+| `catppuccin-light`  | [Catppuccin](https://catppuccin.com/) Latte palette |
+| `catppuccin-dark`   | Catppuccin Frappe palette |
+| `catppuccin-auto`   | Catppuccin, auto-switching |
+| `ayu-light`         | [Ayu](https://github.com/ayu-theme) light palette |
+| `ayu-dark`          | Ayu mirage dark palette |
+| `ayu-auto`          | Ayu, auto-switching |
+
+## Custom Theme
+
+Define a theme mixin in `assets/_custom.scss`
+
+```scss
+@mixin theme-mytheme {
+  --body-background: #fafafa;
+  --body-font-color: #333;
+  --color-link: #0066cc;
+  --color-visited-link: #6633cc;
+}
+```
+
+Then set `BookTheme = 'mytheme'`. The theme uses `@include theme-{{ .Site.Params.BookTheme }}` to select the mixin at build time.
+
+For auto-switching themes (light/dark based on OS preference), see the `theme-auto` mixin in `assets/_defaults.scss` as a reference.
+
+## CSS Custom Properties
+
+Override CSS custom properties in `_custom.scss` to adjust the current theme. The full set of properties is defined in [`assets/_defaults.scss`](https://github.com/alex-shpak/hugo-book/blob/main/assets/_defaults.scss).
+
+## Custom Styles
+
+The theme includes an empty `assets/_custom.scss` file that is loaded after all theme styles. Create this file in your project's `assets/` directory to add custom CSS without overriding the entire stylesheet.
+
+```scss
+// assets/_custom.scss
+
+.book-page {
+  max-width: 60rem;
+}
+
+.book-menu nav {
+  font-size: 0.9rem;
+}
+```
+
+## SCSS Plugins
+
+The theme ships with optional SCSS plugins. Import them in your `_custom.scss`:
+
+```scss
+@import "plugins/numbered"; /* Automatically number headings in the content area */
+@import "plugins/scrollbars"; /* Style scrollbars in the sidebar and content area */
+```
+
+## SCSS Variables
+
+Layout variables like sidebar width, breakpoints, and padding are defined in [`assets/_defaults.scss`](https://github.com/alex-shpak/hugo-book/blob/main/assets/_defaults.scss). Override them in your `_custom.scss`.
+
+## Override Priority
+
+Hugo's [lookup order](https://gohugo.io/templates/lookup-order/) lets you override any theme file by creating the same file in your project:
+
+- `layouts/`: Override templates and partials
+- `assets/`: Override SCSS and JavaScript
+- `static/`: Override static files (favicon, images)
+- `i18n/`: Override or add translations

exampleSite/content.en/docs/getting-started/_index.md

@@ -0,0 +1,6 @@
+---
+title: Getting Started
+weight: 10
+bookFlatSection: true
+bookIcon: rocket
+---

exampleSite/content.en/docs/getting-started/configuration.md

@@ -1,4 +1,5 @@
 ---
+title: Configuration
 weight: 30
 ---
 
@@ -50,12 +51,19 @@ All theme parameters are set under `[params]` in your site config. Every paramet
   # By default uses Disqus; override partials/docs/comments.html for others
   BookComments = true
 
-  # Enable portable markdown links (resolve relative .md links)
+  # /!\ Experimental, may change or be removed.
-  # Values: false, 'warning', 'error'
+  # Enable portable markdown links to resolve relative .md links to Hugo URLs.
+  # Lets you write [text](./other.md) instead of Hugo's relref shortcode.
+  #   false     - disabled, relative .md links not resolved
+  #   'warning' - enabled, prints a build warning if linked page doesn't exist
+  #   'error'   - enabled, fails the build if linked page doesn't exist
   BookPortableLinks = false
 
-  # Enable service worker for offline caching
+  # /!\ Experimental, may change or be removed.
-  # Values: false, true, 'precache'
+  # Register a service worker for offline access to visited pages.
+  #   false      - disabled (default)
+  #   true       - caches pages as you visit them
+  #   'precache' - pre-populates cache with all site pages on first load
   BookServiceWorker = false
 
   # Only show languages that have translations for current page
@@ -126,52 +134,3 @@ The theme supports plain text output alongside HTML, useful for accessibility an
   section = ['html', 'txt']
 ```
 
-## Portable Links
-
-> [!WARNING]
-> Experimental feature. May change or be removed.
-
-Portable links resolve relative markdown links (`[text](./other-page.md)` or `[text](/docs/other-page.md)`) to the correct Hugo URLs. This lets you write standard markdown that works in both text editors and the rendered site.
-
-```toml {filename=hugo.toml}
-[params]
-  BookPortableLinks = 'warning'
-```
-
-`false`
-: Disabled. Relative `.md` links are not resolved.
-
-`'warning'`
-: Enabled. Hugo prints a warning during build if a linked page doesn't exist.
-
-`'error'`
-: Enabled. Hugo fails the build if a linked page doesn't exist.
-
-With portable links enabled, you can write
-
-```markdown
-See [Configuration](./configuration.md) for details.
-```
-
-Instead of Hugo's `relref` shortcode. Both image links and page links are resolved.
-
-## Service Worker
-
-> [!WARNING]
-> Experimental feature. May change or be removed.
-
-Hugo Book can register a service worker for offline access to visited pages.
-
-```toml {filename=hugo.toml}
-[params]
-  BookServiceWorker = 'precache'
-```
-
-`false`
-: Disabled (default).
-
-`true`
-: Enables a service worker that caches pages as you visit them for offline reading.
-
-`'precache'`
-: Enables a service worker that pre-populates the cache with all site pages on first load. Visited resources are also cached.

exampleSite/content.en/docs/getting-started/create-a-site.md

@@ -2,7 +2,7 @@
 weight: 20
 ---
 
-# Getting Started
+# Create a Site
 
 ## Prerequisites
 
@@ -21,7 +21,7 @@ git submodule update --init --remote
 hugo server --minify
 ```
 
-By default, the theme renders pages under `docs/` section as the sidebar menu. See [Content Organization](/docs/content/) for details.
+By default, the theme renders pages under `docs/` section as the sidebar menu. See [Content Organisation](/docs/content/organisation/) for details.
 
 ## Installation Methods
 
@@ -98,4 +98,4 @@ theme = 'hugo-book'
   unsafe = true
 ```
 
-See [Configuration](/docs/configuration/) for the full list of parameters.
+See [Configuration](/docs/getting-started/configuration/) for the full list of parameters.

exampleSite/content.en/docs/getting-started/introduction.md

@@ -16,7 +16,7 @@ Theme as an extendable base.
 Long-term maintainability.
 : Few dependencies means fewer things to break. The theme avoids heavy JavaScript libraries, CSS frameworks, and complex build pipelines.
 
-[Get Started](/docs/getting-started/)
+[Get Started](/docs/getting-started/create-a-site/)
 
 ## Links
 - [Source code](https://github.com/alex-shpak/hugo-book)

exampleSite/content.en/docs/shortcodes/experimental/_index.md

@@ -1,3 +0,0 @@
----
-bookCollapseSection: true
----

exampleSite/hugo.toml

@@ -58,14 +58,9 @@ enableGitInfo = true
   weight = 3
 
 [menu]
-[[menu.home]]
-  name = 'About'
-  pageRef = '/docs/introduction/'
-  weight = 1
-
 [[menu.home]]
   name = 'Documentation'
-  pageRef = '/docs/getting-started/'
+  pageRef = '/docs/getting-started/introduction'
   weight = 2
 
 [[menu.home]]

exampleSite/hugo.yaml

@@ -55,11 +55,8 @@ languages:
 
 menu:
   home:
-    - name: "About"
-      pageRef: "/docs/introduction/"
-      weight: 1
     - name: "Documentation"
-      pageRef: "/docs/getting-started/"
+      pageRef: "/docs/getting-started/introduction"
       weight: 2
     - name: "Showcases"
       pageRef: "/showcases/"

layouts/_partials/docs/icon.html

@@ -1,2 +1,2 @@
-{{- $icon := resources.Get (printf "icons/%s.svg" .) -}}
+{{- $icon := resources.GetMatch (printf "icons/%s.*" .) -}}
 {{- return $icon.RelPermalink -}}