blob: e9bc4478dbd76dcb931c8581dd1128f98025b639 (
plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
# Hugo Book Theme
### [Hugo](https://gohugo.io) documentation theme as simple as plain book
## Features
* Clean simple design
* Mobile friendly
* Customizable
* Designed to not interfere with main website
* Zero initial configuration
## Installation
Navigate to your hugo website root and run:
```
git clone git@github.com:alex-shpak/hugo-book.git themes/book
```
Then run hugo (or set `theme: book` in configuration file)
```
hugo server --theme book
```
## Menu
### File tree menu (default)
By default theme will render pages from `content/docs` section as menu in a tree structure.
You can set `title` and `weight` in front matter of pages to adjust order and titles in menu.
### Leaf bundle menu
You can also use leaf bundle and content of it's `index.md` as
menu.
Given you have this file structure
```
├── content
│ └── docs
│ ├── page-one.md
│ └── page-two.md
```
Create file `content/docs/menu/index.md` with content
```md
---
headless: true
---
- [Book Example](/docs/)
- [Page One](/docs/page-one)
- [Page Two](/docs/page-two)
```
And Enable it by settings `BookMenuBundle: /docs/menu` in Site configuration
- [Example menu](exampleSite/content/menu/index.md)
- [Example config file](exampleSite/config.yml)
- [Leaf bundles](https://gohugo.io/content-management/page-bundles/)
## Configuration
### Site Configuration
There are few configuration options you can add to your `config.yml|json|toml` file
```yaml
# (Optional) Set this to true if you use captial letters in file names
disablePathToLower: true
params:
# (Optional, default true) Show or hide table of contents globally
# You can also specify this parameter per page in front matter
BookShowToC: true
# (Optional, default none) Set leaf bundle to render as side menu
# When not specified file structure and weights will be used
BookMenuBundle: /docs/menu
# (Optional, default docs) Specify section of content to render as menu
# You can also set value to "*" to render all sections to menu
BookSection: docs
```
### Page Configuration
You can specify additional params per page in front matter
```yaml
---
# Set type to 'docs' if you want to render page outside of configured section or if you render section other than 'docs'
type: docs
# Set page weight to re-arrange items in file-tree menu (if BookMenuBundle not set)
weight: 10
# (Optional) Set to mark page as flat section in file-tree menu (if BookMenuBundle not set)
bookFlatSection: true
# (Optional) Set to hide table of contents, overrides global value
bookShowToC: false
---
```
### Partials
There are few empty partials you can override in `layouts/partials/`
| Partial | Placement |
| -- | -- |
| `layouts/partials/docs/inject/head.html` | Before closing `<head>` tag |
| `layouts/partials/docs/inject/body.html` | Before closing `<body>` tag |
| `layouts/partials/docs/inject/menu-before.html` | At the beginning of `<nav>` menu block |
| `layouts/partials/docs/inject/menu-after.html` | At the end of `<nav>` menu block |
## Contributing
Contributions are welcome and I will review and consider pull requests.
Primary goals are:
- Keep it simple
- Keep minimal (or zero) default configuration
- Avoid interference with user-defined layouts
Feel free to open issue if you missing some configuration or customisation option.
## License
[MIT](LICENSE)
|
