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
@@ -0,0 +1,6 @@
+---
+title: Getting Started
+weight: 10
+bookFlatSection: true
+bookIcon: rocket
+---
@@ -0,0 +1,136 @@
+---
+title: Configuration
+weight: 30
+---
+
+# Configuration
+
+All theme parameters are set under `[params]` in your site config. Every parameter is optional.
+
+## Theme Parameters
+
+```toml {filename=hugo.toml}
+[params]
+  # Color theme: 'light', 'dark' or 'auto'
+  # Auto switches based on OS/browser preference
+  BookTheme = 'light'
+
+  # Show table of contents on right side of pages
+  # Can also be set per-page via frontmatter
+  BookToC = true
+
+  # Path to favicon file relative to 'static' directory
+  BookFavicon = 'favicon.png'
+
+  # Path to logo image file relative to 'static' directory
+  BookLogo = 'logo.png'
+
+  # Root section to render as sidebar menu
+  # Default: 'docs'
+  BookSection = 'docs'
+
+  # Repository URL, used for edit and commit links
+  BookRepo = 'https://github.com/user/repo'
+
+  # Template for "Last Modified" commit link in page footer
+  # Requires enableGitInfo = true in site config
+  # Available context: .Site, .Page, .GitInfo
+  BookLastChangeLink = '{{ .Site.Params.BookRepo }}/commit/{{ .GitInfo.Hash }}'
+
+  # Template for "Edit this page" link in page footer
+  # Available context: .Site, .Page, .Path
+  BookEditLink = '{{ .Site.Params.BookRepo }}/edit/main/{{ .Path }}'
+
+  # Date format used in git info and blog posts
+  BookDateFormat = 'January 2, 2006'
+
+  # Enable full-text search with fuse.js
+  BookSearch = true
+
+  # Enable comments template on pages
+  # By default uses Disqus; override partials/docs/comments.html for others
+  BookComments = true
+
+  # /!\ Experimental, may change or be removed.
+  # 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
+
+  # /!\ Experimental, may change or be removed.
+  # 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
+  BookTranslatedOnly = false
+```
+
+## Search
+
+Full-text search is enabled by default using [Fuse.js](https://www.fusejs.io/). The search index is built at page load from a generated JSON file.
+
+```toml {filename=hugo.toml}
+[params]
+  BookSearch = true
+```
+
+To exclude a page from the search index, set `bookSearchExclude: true` in its frontmatter.
+
+If search is not working, verify that `baseURL` in your config matches the URL where the site is hosted. A mismatch prevents the search index from loading.
+
+## Hugo Site Configuration
+
+These Hugo settings are relevant for the theme
+
+```toml {filename=hugo.toml}
+# Preserve URL casing (recommended)
+disablePathToLower = true
+
+# Enable git metadata for "Last Modified" footer
+enableGitInfo = true
+```
+
+## Markup
+
+### Goldmark Renderer
+
+The `unsafe` option is **required** for Mermaid and KaTeX shortcodes to render correctly
+
+```toml {filename=hugo.toml}
+[markup.goldmark.renderer]
+  unsafe = true
+```
+
+### Table of Contents
+
+Control the heading levels included in the table of contents
+
+```toml {filename=hugo.toml}
+[markup.tableOfContents]
+  startLevel = 1
+  endLevel = 4
+```
+
+The `startLevel` and `endLevel` values apply globally. Individual pages can toggle the ToC on or off with the `bookToC` frontmatter parameter.
+
+## Output Formats
+
+The theme supports plain text output alongside HTML, useful for accessibility and LLMs
+
+```toml {filename=hugo.toml}
+[outputFormats.txt]
+  mediaType = 'text/plain'
+  baseName = 'source'
+  isPlainText = true
+
+[outputs]
+  home = ['html', 'txt', 'rss']
+  page = ['html', 'txt']
+  section = ['html', 'txt']
+```
+
@@ -0,0 +1,101 @@
+---
+weight: 20
+---
+
+# Create a Site
+
+## Prerequisites
+
+- [Hugo](https://gohugo.io/installation/) **extended** edition (required for SCSS processing)
+- [Git](https://git-scm.com/downloads) (for theme installation using git submodules)
+- [Go](https://go.dev/dl/) (for theme installation using Hugo Modules)
+
+## Quick Start
+
+Use the [starter repository](https://github.com/alex-shpak/hugo-book-starter) to get a working site in seconds. It can also be used as a [GitHub template](https://github.com/alex-shpak/hugo-book-starter/generate) to create a new repository.
+
+```shell
+git clone https://github.com/alex-shpak/hugo-book-starter documentation
+cd documentation
+git submodule update --init --remote
+hugo server --minify
+```
+
+By default, the theme renders pages under `docs/` section as the sidebar menu. See [Content Organisation](/docs/content/organisation/) for details.
+
+## Installation Methods
+
+{{< tabs >}}
+
+{{% tab "Git Submodule" %}}
+The simplest approach. The theme is vendored directly into your repository.
+
+```shell
+git init
+git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book
+```
+
+Set the theme in your config
+
+```toml {filename=hugo.toml}
+theme = 'hugo-book'
+```
+
+To update the theme later
+
+```shell
+git submodule update --remote --merge
+```
+{{% /tab %}}
+
+{{% tab "Hugo Module" %}}
+Uses [Hugo Modules](https://gohugo.io/hugo-modules/) (requires [Go](https://go.dev/dl/)).
+
+Initialize your site as a module
+
+```shell
+hugo mod init github.com/user/my-docs
+```
+
+Add the theme import to your config
+
+```toml {filename=hugo.toml}
+[module]
+[[module.imports]]
+  path = 'github.com/alex-shpak/hugo-book'
+```
+
+To update the theme later
+
+```shell
+hugo mod get -u
+```
+{{% /tab %}}
+
+{{% tab "Manual Download" %}}
+Download the theme from [GitHub releases](https://github.com/alex-shpak/hugo-book/releases) and extract it to `themes/hugo-book`.
+
+Set the theme in your config
+
+```toml {filename=hugo.toml}
+theme = 'hugo-book'
+```
+
+To update, download and extract the new release again.
+{{% /tab %}}
+
+{{< /tabs >}}
+
+## Minimal Configuration
+
+```toml {filename=hugo.toml}
+baseURL = 'https://example.com/'
+title = 'My Documentation'
+theme = 'hugo-book'
+
+# Required for mermaid and katex shortcodes
+[markup.goldmark.renderer]
+  unsafe = true
+```
+
+See [Configuration](/docs/getting-started/configuration/) for the full list of parameters.
@@ -0,0 +1,23 @@
+---
+weight: 10
+---
+# Introduction
+
+Hugo Book is a documentation theme for [Hugo](https://gohugo.io). It provides a clean, readable layout for technical docs with minimal dependencies and no build tooling beyond Hugo itself.
+
+## Design Goals
+
+Minimalism over features.
+: The theme ships only what most documentation sites need: a sidebar menu, search, and a few shortcodes. There is no attempt to cover every use case. CSS is written by hand, not generated by a framework. JavaScript is optional for core navigation.
+
+Theme as an extendable base.
+: Hugo Book is meant to be extended and adapted. 'Inject' partials, custom SCSS, and Hugo's template override system let you change any part of the theme without modifying the source, while keeping the codebase intentionally small.
+
+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/create-a-site/)
+
+## Links
+- [Source code](https://github.com/alex-shpak/hugo-book)
+- [Hugo documentation](https://gohugo.io/documentation/)