Big documentation rewrite, move docs to example site
This commit is contained in:
Alex Shpak
@@ -0,0 +1,55 @@
|
||||
---
|
||||
weight: 40
|
||||
title: Content & Structure
|
||||
bookCollapseSection: true
|
||||
---
|
||||
|
||||
# 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.
|
||||
@@ -0,0 +1,54 @@
|
||||
---
|
||||
weight: 3
|
||||
---
|
||||
|
||||
# Blog
|
||||
|
||||
Hugo Book includes templates for blog-style posts with dates, tags, and pagination. Blog functionality is very basic.
|
||||
|
||||
## Setup
|
||||
|
||||
Create a `posts/` section in your content directory
|
||||
|
||||
```
|
||||
content/
|
||||
└── posts/
|
||||
├── _index.md
|
||||
└── my-first-post.md
|
||||
```
|
||||
|
||||
Add the blog section to a menu so readers can find it
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Blog
|
||||
menu:
|
||||
after:
|
||||
weight: 5
|
||||
---
|
||||
```
|
||||
|
||||
## Post Frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "My First Post"
|
||||
date: 2025-01-15
|
||||
tags: ["hugo", "documentation"]
|
||||
categories: ["Guides"]
|
||||
---
|
||||
```
|
||||
|
||||
## Thumbnails
|
||||
|
||||
Posts can display a thumbnail image. By default the theme looks for a file matching `thumbnail.*` in the post's page bundle. Override the pattern per-post
|
||||
|
||||
```yaml
|
||||
---
|
||||
bookPostThumbnail: "cover.*"
|
||||
---
|
||||
```
|
||||
|
||||
## Date Format
|
||||
|
||||
The date display format is configured site-wide via `BookDateFormat`. See [Configuration](/docs/configuration/) for details.
|
||||
@@ -0,0 +1,70 @@
|
||||
---
|
||||
weight: 2
|
||||
---
|
||||
|
||||
# Menu System
|
||||
|
||||
Hugo Book supports two types of menus: an automatic file-tree menu built from your content structure, and Hugo's standard menu system for additional navigation.
|
||||
|
||||
## File-Tree Menu
|
||||
|
||||
The sidebar menu is automatically generated from pages in the `BookSection` directory (default: `docs/`). The hierarchy mirrors your directory structure.
|
||||
|
||||
Control how sections appear with [page frontmatter](/docs/content/pages/).
|
||||
|
||||
## Hugo Menus
|
||||
|
||||
The theme renders three Hugo menu locations:
|
||||
|
||||
| Menu | Location
|
||||
| -- | --
|
||||
| `menu.before` | Rendered **above** the file-tree menu.
|
||||
| `menu.after` | Rendered **below** the file-tree menu.
|
||||
| `menu.home` | Rendered on the landing page header (only on pages with `layout: landing`).
|
||||
|
||||
### Configuration
|
||||
|
||||
Define menus in your site config
|
||||
|
||||
```toml {filename=hugo.toml}
|
||||
[[menu.before]]
|
||||
name = 'Overview'
|
||||
url = '/overview/'
|
||||
weight = 1
|
||||
|
||||
[[menu.after]]
|
||||
name = 'Github'
|
||||
url = 'https://github.com/user/repo'
|
||||
weight = 10
|
||||
|
||||
[[menu.after]]
|
||||
name = 'Hugo Themes'
|
||||
url = 'https://themes.gohugo.io/themes/hugo-book/'
|
||||
weight = 20
|
||||
```
|
||||
|
||||
Or add pages to menus via frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: Blog
|
||||
menu:
|
||||
after:
|
||||
weight: 5
|
||||
---
|
||||
```
|
||||
|
||||
### Menu Item Parameters
|
||||
|
||||
Menu items support these params under `[params]`:
|
||||
|
||||
```toml {filename=hugo.toml}
|
||||
[[menu.after]]
|
||||
name = 'Example'
|
||||
url = '/example/'
|
||||
weight = 10
|
||||
[menu.after.params]
|
||||
bookIcon = 'star' # Icon name to display next to the item
|
||||
bookNewTab = true # Open the link in a new tab
|
||||
class = 'custom-class' # CSS class to add to the menu item
|
||||
```
|
||||
@@ -0,0 +1,46 @@
|
||||
---
|
||||
title: Multi-Language
|
||||
weight: 4
|
||||
---
|
||||
|
||||
# Multi-Language Support
|
||||
|
||||
Hugo Book supports Hugo's [multilingual mode](https://gohugo.io/content-management/multilingual/) with content translation by directory.
|
||||
|
||||
## Configuration
|
||||
|
||||
Define languages in your site config
|
||||
|
||||
```toml {filename=hugo.toml}
|
||||
[languages]
|
||||
[languages.en]
|
||||
label = 'English'
|
||||
contentDir = 'content.en'
|
||||
weight = 1
|
||||
|
||||
[languages.zh]
|
||||
label = 'Chinese'
|
||||
contentDir = 'content.zh'
|
||||
weight = 2
|
||||
|
||||
[languages.he]
|
||||
label = 'Hebrew'
|
||||
contentDir = 'content.he'
|
||||
direction = 'rtl'
|
||||
weight = 3
|
||||
```
|
||||
|
||||
A language selector dropdown appears automatically when multiple languages are configured.
|
||||
|
||||
## RTL Support
|
||||
|
||||
Set `direction = 'rtl'` on a language to enable right-to-left layout. The entire page layout, including the sidebar menu, mirrors automatically.
|
||||
|
||||
## Translation Dropdown
|
||||
|
||||
By default, all configured languages appear in the selector. To only show languages that have a translation for the current page
|
||||
|
||||
```toml {filename=hugo.toml}
|
||||
[params]
|
||||
BookTranslatedOnly = true
|
||||
```
|
||||
@@ -0,0 +1,67 @@
|
||||
---
|
||||
weight: 1
|
||||
---
|
||||
|
||||
# Page Frontmatter
|
||||
|
||||
Every page can use these [frontmatter](https://gohugo.io/content-management/front-matter/) parameters to control its behavior in the theme.
|
||||
|
||||
{{< tabs >}}
|
||||
{{% tab "YAML" %}}
|
||||
```yaml
|
||||
---
|
||||
title: My Page
|
||||
weight: 10
|
||||
bookToC: true
|
||||
bookCollapseSection: true
|
||||
---
|
||||
```
|
||||
{{% /tab %}}
|
||||
|
||||
{{% tab "TOML" %}}
|
||||
```toml
|
||||
+++
|
||||
title = 'My Page'
|
||||
weight = 10
|
||||
bookToC = true
|
||||
bookCollapseSection = true
|
||||
+++
|
||||
```
|
||||
{{% /tab %}}
|
||||
|
||||
{{% tab "JSON" %}}
|
||||
```json
|
||||
{
|
||||
"title": "My Page",
|
||||
"weight": 10,
|
||||
"bookToC": true,
|
||||
"bookCollapseSection": true
|
||||
}
|
||||
```
|
||||
{{% /tab %}}
|
||||
{{< /tabs >}}
|
||||
|
||||
## Navigation
|
||||
|
||||
These parameters control how the page appears in the sidebar menu. Set in page frontmatter.
|
||||
|
||||
| Parameter | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `weight` | | Menu ordering. Lower values appear first. Without weight, pages are sorted alphabetically. |
|
||||
| `bookHidden` | `false` | Hide the page from the sidebar menu. The page is still accessible by URL. |
|
||||
| `bookCollapseSection` | `false` | Make a section collapsible in the sidebar. Subsections are hidden until clicked. |
|
||||
| `bookFlatSection` | `false` | Display subsection pages at the same level instead of nesting them. |
|
||||
| `bookHref` | | Override the menu link with an external URL. |
|
||||
| `bookIcon` | | Display an icon next to the menu entry. |
|
||||
|
||||
## Content Display
|
||||
|
||||
These parameters control page content rendering. Set in page frontmatter.
|
||||
|
||||
| Parameter | Default | Description |
|
||||
| --- | --- | --- |
|
||||
| `bookToC` | | Show or hide the table of contents. Overrides the site-level `BookToC` setting. |
|
||||
| `bookComments` | | Show or hide comments. Overrides the site-level `BookComments` setting. |
|
||||
| `bookSearchExclude` | `false` | Exclude this page from the search index. |
|
||||
|
||||
See [Blog](/docs/content/blog/) for post-specific frontmatter.
|
||||
Reference in New Issue
Block a user