Restructure exampleSite once again, improve sections and flow
This commit is contained in:
Alex Shpak
@@ -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>
|
||||
|
After Width: | Height: | Size: 536 B |
@@ -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>
|
||||
|
After Width: | Height: | Size: 761 B |
@@ -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/),
|
||||
[Cards](/docs/shortcodes/experimental/cards/),
|
||||
[Tabs](/docs/shortcodes/tabs/),
|
||||
[Images](/docs/shortcodes/experimental/images/),
|
||||
[Asciinema](/docs/shortcodes/asciinema/),
|
||||
[KaTex](/docs/shortcodes/katex/),
|
||||
[Mermaid](/docs/shortcodes/mermaid/) and others.
|
||||
[Columns](/docs/content/shortcodes/columns/),
|
||||
[Cards](/docs/content/shortcodes/cards/),
|
||||
[Tabs](/docs/content/shortcodes/tabs/),
|
||||
[Images](/docs/content/shortcodes/images/),
|
||||
[Asciinema](/docs/content/shortcodes/asciinema/),
|
||||
[KaTex](/docs/content/shortcodes/katex/),
|
||||
[Mermaid](/docs/content/shortcodes/mermaid/) and others.
|
||||
{{< /card >}}
|
||||
|
||||
- {{< card >}}
|
||||
|
||||
@@ -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
|
||||
|
||||
+2
-2
@@ -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 >}}
|
||||
@@ -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
|
||||
|
||||
@@ -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>
|
||||
```
|
||||
@@ -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
|
||||
@@ -0,0 +1,6 @@
|
||||
---
|
||||
title: Getting Started
|
||||
weight: 10
|
||||
bookFlatSection: true
|
||||
bookIcon: rocket
|
||||
---
|
||||
+12
-53
@@ -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)
|
||||
# Values: false, 'warning', 'error'
|
||||
# /!\ 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
|
||||
|
||||
# Enable service worker for offline caching
|
||||
# Values: false, true, 'precache'
|
||||
# /!\ 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
|
||||
@@ -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.
|
||||
+3
-3
@@ -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.
|
||||
+1
-1
@@ -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)
|
||||
@@ -1,3 +0,0 @@
|
||||
---
|
||||
bookCollapseSection: true
|
||||
---
|
||||
@@ -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]]
|
||||
|
||||
@@ -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/"
|
||||
|
||||
@@ -1,2 +1,2 @@
|
||||
{{- $icon := resources.Get (printf "icons/%s.svg" .) -}}
|
||||
{{- $icon := resources.GetMatch (printf "icons/%s.*" .) -}}
|
||||
{{- return $icon.RelPermalink -}}
|
||||
|
||||
Reference in New Issue
Block a user