Restructure exampleSite once again, improve sections and flow

2026-05-19 11:22:59 +02:00
parent 9ab28a9b36
commit 118c5354bb
34 changed files with 245 additions and 275 deletions
@@ -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.
@@ -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.
@@ -1,5 +1,5 @@
 ---
-weight: 2
+weight: 30
 ---

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

 # Multi-Language Support
@@ -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.
@@ -1,5 +1,5 @@
 ---
-weight: 1
+weight: 20
 ---

 # Page Frontmatter
@@ -0,0 +1,20 @@
+---
+weight: 60
+bookCollapseSection: true
+---
+
+# Shortcodes
+
+Hugo Book includes shortcodes for common documentation patterns. All interactive shortcodes work without JavaScript using CSS-only techniques.
+
+Hugo shortcodes use two delimiter styles:
+
+`{{</* shortcode */>}}`
+: Renders inner content as plain HTML. Use for shortcodes that don't contain markdown.
+
+`{{%/* shortcode */%}}`
+: Processes inner content as markdown. Use when the shortcode body contains markdown formatting.
+
+> [!NOTE]
+> Use `{{%/* shortcode */%}}` when the body contains markdown that needs to be rendered. `{{</* shortcode */>}}` passes content as-is without markdown processing.
+> When nesting shortcodes (e.g. tabs inside columns), the outer shortcode must use `{{%/* shortcode */%}}` for the inner shortcodes and markdown to be processed.
@@ -0,0 +1,32 @@
+# Asciinema
+
+Embed terminal recordings with the [Asciinema](https://asciinema.org/) player.
+
+## Syntax
+
+```tpl
+{{</* asciinema
+  cast="recording.cast"
+  loop=true
+  autoplay=true
+  speed=2 */>}}
+```
+
+The `cast` parameter accepts page resources, site resources, or remote URLs.
+
+## Example
+
+{{< asciinema
+  cast="asciinema-627097.cast"
+  loop=true
+  autoplay=true
+  speed=2 >}}
+
+## Parameters
+
+`cast`
+: Path to the `.cast` file. Can be a local resource or a remote URL.
+
+All other parameters are passed directly to the Asciinema player. See the [Asciinema player options](https://docs.asciinema.org/manual/player/options/) for the full list.
+
+Common options: `autoplay`, `loop`, `speed`, `theme`, `cols`, `rows`, `idleTimeLimit`, `preload`.
@@ -0,0 +1,43 @@
+# Badges
+
+Inline labels for annotating content with status, versions, or metadata.
+
+## Syntax
+
+```tpl
+{{</* badge style="info" title="Hugo" value="0.158" */>}}
+```
+
+## Styles
+
+| Shortcode | Output |
+| -- | -- |
+| `{{</* badge style="info" title="Hugo" value="0.158" */>}}` | {{< badge style="info" title="Hugo" value="0.158" >}} |
+| `{{</* badge style="success" title="Build" value="Passing" */>}}` | {{< badge style="success" title="Build" value="Passing" >}} |
+| `{{</* badge style="warning" title="Coverage" value="25%" */>}}` | {{< badge style="warning" title="Coverage" value="25%" >}} |
+| `{{</* badge style="danger" title="Issues" value="120" */>}}` | {{< badge style="danger" title="Issues" value="120" >}} |
+| | |
+| `{{</* badge style="info" title="Title" */>}}` | {{< badge style="info" title="Title" >}} |
+| `{{</* badge style="info" value="Value" */>}}` | {{< badge style="info" value="Value" >}} |
+| `{{</* badge value="Default" */>}}` | {{< badge value="Default" >}} |
+
+## Use in Links
+
+Wrap a badge in a markdown link
+
+```tpl
+[{{</* badge title="Hugo" value="0.158" */>}}](https://github.com/gohugoio/hugo/releases/tag/v0.158.0)
+```
+
+[{{< badge title="Hugo" value="0.158" >}}](https://github.com/gohugoio/hugo/releases/tag/v0.158.0)
+
+## Parameters
+
+`style`
+: Visual style. One of: `default`, `info`, `success`, `warning`, `danger`, `note`, `tip`, `important`, `caution`.
+
+`title`
+: Label text (left side).
+
+`value`
+: Value text (right side).
@@ -0,0 +1,26 @@
+# Buttons
+
+Styled links that can point to local pages or external URLs. External links automatically open in a new tab.
+
+## Syntax
+
+```tpl
+{{</* button relref="/" [class="..."] */>}}Get Home{{</* /button */>}}
+{{</* button href="https://github.com/alex-shpak/hugo-book" */>}}Github{{</* /button */>}}
+```
+
+## Example
+
+{{<button href="/">}}Home{{</button>}}
+{{<button href="https://github.com/alex-shpak/hugo-book">}}Github{{</button>}}
+
+## Parameters
+
+`href`
+: URL for external links.
+
+`relref`
+: Hugo page reference for internal links.
+
+`class`
+: Additional CSS classes.
@@ -0,0 +1,47 @@
+# Cards
+
+Content blocks with optional images and links. Often used with [Columns](/docs/content/shortcodes/columns) for grid layouts.
+
+## Syntax
+
+```tpl
+{{</* card [href="..."] [image="..."] [title="..."] */>}}
+Markdown content
+{{</* /card */>}}
+```
+
+## Example
+
+{{% columns %}}
+- {{< card image="placeholder.svg" >}}
+  ### With Image
+  Cards can display an image above the content.
+  {{< /card >}}
+
+- {{< card href="/docs/content/shortcodes/cards" >}}
+  ### With Link {anchor=false}
+  When `href` is set, the entire card becomes clickable.
+  {{< /card >}}
+
+- {{< card title="Card" >}}
+  ### Plain Card
+  A basic card with no image or link, used for grouping related content.
+  {{< /card >}}
+{{% /columns %}}
+
+## Parameters
+
+`href`
+: Makes the card a link. The entire card area becomes clickable.
+
+`image`
+: Path to an image displayed above the card content. Supports page resources and URLs.
+
+`title`
+: Accessible title for the card.
+
+`alt`
+: Alt text for the card image.
+
+`class`
+: Additional CSS classes.
@@ -0,0 +1,47 @@
+# Columns
+
+Organize content horizontally. Renders a markdown list as up to 3 side-by-side columns.
+
+## Syntax
+
+```tpl
+{{%/* columns [ratio="1:1"] [class="..."] */%}}
+- ### Left
+  Content...
+
+- ### Right
+  Content...
+{{%/* /columns */%}}
+```
+
+## Example
+
+{{% columns %}}
+- ### File-Tree Menu
+  The sidebar menu is automatically generated from your content directory structure. Pages are ordered by `weight` frontmatter.
+
+- ### Hugo Menus
+  Additional menu entries can be added above or below the file-tree using Hugo's standard menu system in your site config.
+
+- ### Landing Menu
+  Pages with `layout: landing` use a separate menu defined under `menu.home` for header navigation.
+{{% /columns %}}
+
+## Custom Ratio
+
+Set relative column widths with the `ratio` parameter
+
+```tpl
+{{%/* columns ratio="1:2" */%}}
+- ### Sidebar
+- ### Content Area
+{{%/* /columns */%}}
+```
+
+{{% columns ratio="1:2" %}}
+- ### File-Tree Menu
+  The sidebar menu is automatically generated from your content directory structure. Pages are ordered by `weight` frontmatter.
+
+- ### Hugo Menus
+  Additional menu entries can be added above or below the file-tree using Hugo's standard menu system in your site config.
+{{% /columns %}}
@@ -0,0 +1,37 @@
+# Details
+
+Collapsible content using the HTML5 `<details>` element.
+
+## Syntax
+
+Positional arguments:
+```tpl
+{{%/* details "Title" [open] */%}}
+Markdown content
+{{%/* /details */%}}
+```
+
+Named parameters:
+```tpl
+{{%/* details title="Title" open=true */%}}
+Markdown content
+{{%/* /details */%}}
+```
+
+## Example
+
+{{% details "What Hugo version is required?" %}}
+Hugo Book requires Hugo {x} or later, extended edition. The extended edition is needed for SCSS processing.
+{{% /details %}}
+
+{{% details "How do I override the theme?" open %}}
+Create matching files in your project's `layouts/` or `assets/` directory. Hugo's lookup order will use your files over the theme's.
+{{% /details %}}
+
+## Parameters
+
+`title` (or first positional argument)
+: The summary text shown when collapsed.
+
+`open` (or second positional argument)
+: Start expanded. Default: collapsed.
@@ -0,0 +1,64 @@
+# Hints
+
+Callout blocks for notes, warnings, and other contextual messages. Also supports standard GitHub markdown alerts.
+
+## Syntax
+
+```tpl
+{{%/* hint [info|success|warning|danger] */%}}
+Markdown content
+{{%/* /hint */%}}
+```
+
+Or using markdown alerts
+
+```markdown
+> [!NOTE|TIP|IMPORTANT|WARNING|CAUTION]
+> Markdown content
+```
+
+## Example
+
+{{% hint %}}
+**Default hint**  
+Without a specified type.
+{{% /hint %}}
+
+{{% hint info %}}
+**Info**  
+Use for supplementary information that helps the reader.
+{{% /hint %}}
+
+{{% hint success %}}
+**Success**  
+Use to highlight a recommended approach or positive outcome.
+{{% /hint %}}
+
+{{% hint warning %}}
+**Warning**  
+Use for important caveats or potential issues.
+{{% /hint %}}
+
+{{% hint danger %}}
+**Danger**  
+Use for critical warnings about breaking changes or data loss.
+{{% /hint %}}
+
+## Markdown Alerts
+
+Standard GitHub markdown alert syntax is also supported:
+
+> [!NOTE]
+> The theme requires Hugo **extended** edition for SCSS processing.
+
+> [!TIP]
+> Set `disablePathToLower = true` in your config to preserve URL casing.
+
+> [!IMPORTANT]
+> The `unsafe = true` goldmark setting is required for Mermaid and KaTeX shortcodes.
+
+> [!WARNING]
+> Service worker support is experimental and may change in future releases.
+
+> [!CAUTION]
+> Enabling `BookPortableLinks = 'error'` will fail the build if any markdown link targets are missing.
@@ -0,0 +1,30 @@
+# Images
+
+Enhanced image display with click-to-expand behavior.
+
+## Syntax
+
+```tpl
+{{</* image src="photo.jpg" alt="Description" title="Caption" loading="lazy" */>}}
+```
+
+## Example
+
+{{< image src="placeholder.svg" alt="Placeholder image" title="Click to expand" loading="lazy" >}}
+
+## Parameters
+
+`src`
+: Path to the image. Supports page resources, site resources, and URLs.
+
+`alt`
+: Alternate text for accessibility.
+
+`title`
+: Caption displayed below the image.
+
+`loading`
+: Loading strategy: `lazy`, `eager`, or `auto`.
+
+`class`
+: Additional CSS classes on the `<img>` element.
@@ -0,0 +1,75 @@
+---
+title: KaTeX
+---
+
+# KaTeX
+
+Render math typesetting with [KaTeX](https://katex.org/). The library is loaded automatically on first use.
+
+{{< katex />}}
+
+## Activation
+
+KaTeX is activated on the page by the first use of the shortcode or a `katex` code block. You can force activation with `{{</* katex /*/>}}`, then use delimiters anywhere on the page.
+
+## Block Rendering
+
+Three equivalent ways to render display math:
+
+{{% columns %}}
+
+- **Shortcode**
+  ```tpl
+  {{</* katex display=true >}}
+  f(x) = \int_{-\infty}^\infty
+  \hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
+  {{< /katex */>}}
+  ```
+
+- **Code block**
+  ````
+  ```katex
+  f(x) = \int_{-\infty}^\infty
+  \hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
+  ```
+  ````
+
+- **Dollar delimiters**
+  ```
+  $$
+  f(x) = \int_{-\infty}^\infty
+  \hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
+  $$
+  ```
+
+{{% /columns %}}
+
+Result:
+
+$$
+f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
+$$
+
+## Inline Rendering
+
+| Syntax | Output |
+| -- | -- |
+| `{{</* katex >}}\pi(x){{< /katex */>}}` | {{< katex >}}\pi(x){{< /katex >}} |
+| `\\( \pi(x) \\)` | \\( \pi(x) \\) |
+
+## Configuration
+
+Override KaTeX options by creating `assets/katex.json`. For example, to enable `$...$` inline delimiters
+
+```json
+{
+  "delimiters": [
+    {"left": "$$", "right": "$$", "display": true},
+    {"left": "$", "right": "$", "display": false},
+    {"left": "\\(", "right": "\\)", "display": false},
+    {"left": "\\[", "right": "\\]", "display": true}
+  ]
+}
+```
+
+See [KaTeX options](https://katex.org/docs/options.html) for all available settings.
@@ -0,0 +1,69 @@
+# Mermaid
+
+Render diagrams and charts with [Mermaid](https://mermaid.js.org/). The library is loaded automatically on first use.
+
+> [!TIP]
+> Override Mermaid initialization by creating `assets/mermaid.json` in your project.
+
+## Syntax
+
+Use fenced code blocks (recommended) or the shortcode
+
+````tpl
+```mermaid
+graph LR
+    A --> B
+```
+````
+
+```tpl
+{{</* mermaid [class="..."] */>}}
+graph LR
+    A --> B
+{{</* /mermaid */>}}
+```
+
+## Examples
+
+{{% columns %}}
+
+- ```mermaid
+  flowchart TD
+      A[Content Files] --> B[Hugo Build]
+      B --> C[HTML Output]
+      B --> D[Search Index]
+      B --> E[RSS Feed]
+  ```
+
+  ```mermaid
+  sequenceDiagram
+      Browser->>Hugo: Request page
+      Hugo->>Theme: Apply template
+      Theme->>Browser: Rendered HTML
+      Browser->>Browser: Load shortcodes
+  ```
+
+- ```mermaid
+  pie title Theme Assets
+      "SCSS" : 8
+      "HTML Templates" : 30
+      "JavaScript" : 3
+      "i18n Files" : 35
+  ```
+
+  ```mermaid
+  gitGraph
+     commit id: "init"
+     commit id: "add theme"
+     branch feature
+     checkout feature
+     commit id: "add docs"
+     commit id: "add config"
+     checkout main
+     merge feature
+     commit id: "deploy"
+  ```
+
+{{% /columns %}}
+
+Explore more diagram types on the [Mermaid documentation](https://mermaid.js.org/syntax/flowchart.html).
@@ -0,0 +1,18 @@
+---
+bookHidden: true
+---
+
+# Section
+
+Render child pages of the current section as a definition list with titles and descriptions.
+
+## Syntax
+
+```tpl
+{{</* section [summary] */>}}
+```
+
+## Parameters
+
+`summary`
+: When present, includes the page summary below each title.
@@ -0,0 +1,31 @@
+# Steps
+
+Render an ordered list as a series of numbered steps with visual connectors.
+
+## Syntax
+
+```tpl
+{{%/* steps */%}}
+1. ## Step Title
+   Step description...
+
+2. ## Step Title
+   Step description...
+{{%/* /steps */%}}
+```
+
+## Example
+
+{{% steps %}}
+1. ## Create your site
+   Run `hugo new site my-docs` to scaffold a new Hugo project.
+
+2. ## Add the theme
+   Clone or add hugo-book as a submodule in your `themes/` directory.
+
+3. ## Write content
+   Add markdown files under `content/docs/`. Each file becomes a page in the sidebar menu.
+
+4. ## Deploy
+   Run `hugo` to build the site. The output is in the `public/` directory, ready for any static hosting.
+{{% /steps %}}
@@ -0,0 +1,36 @@
+# Tabs
+
+Organize content by context, for example installation instructions for each supported platform.
+
+## Syntax
+
+```tpl
+{{</* tabs */>}}
+{{%/* tab "First" */%}} Markdown content {{%/* /tab */%}}
+{{%/* tab "Second" */%}} Markdown content {{%/* /tab */%}}
+{{</* /tabs */>}}
+```
+
+## Example
+
+{{< tabs >}}
+
+{{% tab "macOS" %}}
+```shell
+brew install hugo
+```
+{{% /tab %}}
+
+{{% tab "Linux" %}}
+```shell
+sudo snap install hugo
+```
+{{% /tab %}}
+
+{{% tab "Windows" %}}
+```shell
+choco install hugo-extended
+```
+{{% /tab %}}
+
+{{< /tabs >}}