2018-09-13 18:07:55 +02:00
|
|
|
# Hugo Book Theme
|
2018-12-19 22:46:48 +01:00
|
|
|
[](https://travis-ci.org/alex-shpak/hugo-book)
|
2018-09-17 15:09:51 +02:00
|
|
|
### [Hugo](https://gohugo.io) documentation theme as simple as plain book
|
2018-09-13 18:07:55 +02:00
|
|
|
|
2018-10-30 16:37:38 +01:00
|
|
|
|
2018-09-13 18:07:55 +02:00
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
|
2018-09-13 18:07:55 +02:00
|
|
|
## Features
|
|
|
|
|
* Clean simple design
|
|
|
|
|
* Mobile friendly
|
2018-09-17 15:09:51 +02:00
|
|
|
* Customizable
|
|
|
|
|
* Designed to not interfere with main website
|
|
|
|
|
* Zero initial configuration
|
2018-09-13 18:07:55 +02:00
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
|
2018-09-13 18:07:55 +02:00
|
|
|
## Installation
|
2018-09-17 15:09:51 +02:00
|
|
|
Navigate to your hugo website root and run:
|
2018-09-13 18:07:55 +02:00
|
|
|
```
|
2018-11-08 16:03:48 +01:00
|
|
|
git submodule add https://github.com/alex-shpak/hugo-book themes/book
|
2018-09-13 18:07:55 +02:00
|
|
|
```
|
|
|
|
|
|
2018-09-17 15:09:51 +02:00
|
|
|
Then run hugo (or set `theme: book` in configuration file)
|
|
|
|
|
```
|
|
|
|
|
hugo server --theme book
|
|
|
|
|
```
|
2018-09-13 18:07:55 +02:00
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
|
|
|
|
|
## Menu
|
2018-09-17 15:09:51 +02:00
|
|
|
### 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.
|
2018-09-13 18:07:55 +02:00
|
|
|
|
2018-09-17 15:09:51 +02:00
|
|
|
### Leaf bundle menu
|
|
|
|
|
You can also use leaf bundle and content of it's `index.md` as
|
2018-09-17 15:33:04 +02:00
|
|
|
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
|
2018-09-18 01:35:54 +02:00
|
|
|
---
|
|
|
|
|
headless: true
|
|
|
|
|
---
|
|
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
- [Book Example](/docs/)
|
|
|
|
|
- [Page One](/docs/page-one)
|
|
|
|
|
- [Page Two](/docs/page-two)
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
And Enable it by settings `BookMenuBundle: /docs/menu` in Site configuration
|
|
|
|
|
|
2018-10-31 13:12:01 +01:00
|
|
|
- [Example menu](https://github.com/alex-shpak/hugo-book/blob/master/exampleSite/content/menu/index.md)
|
|
|
|
|
- [Example config file](https://github.com/alex-shpak/hugo-book/blob/master/exampleSite/config.yml)
|
2018-09-17 15:09:51 +02:00
|
|
|
- [Leaf bundles](https://gohugo.io/content-management/page-bundles/)
|
2018-09-13 18:07:55 +02:00
|
|
|
|
|
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
## Configuration
|
|
|
|
|
### Site Configuration
|
2018-09-17 15:09:51 +02:00
|
|
|
There are few configuration options you can add to your `config.yml|json|toml` file
|
2018-09-13 18:07:55 +02:00
|
|
|
```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
|
|
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
# (Optional, default none) Set leaf bundle to render as side menu
|
2018-09-13 18:07:55 +02:00
|
|
|
# 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
|
2018-12-06 01:31:24 +01:00
|
|
|
|
|
|
|
|
# (Optional, uncomment and configure url to enable) Enable "Edit this page"
|
|
|
|
|
# links for 'doc' page type. Path should point to 'content' directory of
|
|
|
|
|
# source project.
|
|
|
|
|
BookEditURL: https://github.com/alex-shpak/hugo-book/edit/master/exampleSite/content/
|
2018-09-13 18:07:55 +02:00
|
|
|
```
|
|
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
### Page Configuration
|
|
|
|
|
You can specify additional params per page in front matter
|
2018-09-13 18:07:55 +02:00
|
|
|
```yaml
|
|
|
|
|
---
|
2018-09-17 15:33:04 +02:00
|
|
|
# Set type to 'docs' if you want to render page outside of configured section or if you render section other than 'docs'
|
2018-09-13 18:07:55 +02:00
|
|
|
type: docs
|
|
|
|
|
|
|
|
|
|
# Set page weight to re-arrange items in file-tree menu (if BookMenuBundle not set)
|
|
|
|
|
weight: 10
|
|
|
|
|
|
2018-09-28 01:12:07 +02:00
|
|
|
# (Optional) Set to mark page as flat section in file-tree menu (if BookMenuBundle not set)
|
|
|
|
|
bookFlatSection: true
|
2018-09-13 18:07:55 +02:00
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
# (Optional) Set to hide table of contents, overrides global value
|
2018-09-13 18:07:55 +02:00
|
|
|
bookShowToC: false
|
|
|
|
|
---
|
|
|
|
|
```
|
|
|
|
|
|
2018-09-17 15:09:51 +02:00
|
|
|
### Partials
|
|
|
|
|
There are few empty partials you can override in `layouts/partials/`
|
2018-09-17 15:19:18 +02:00
|
|
|
|
2018-09-28 01:12:07 +02:00
|
|
|
| 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 |
|
2018-09-17 15:09:51 +02:00
|
|
|
|
|
|
|
|
|
|
|
|
|
## 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
|
|
|
|
|
|
2018-09-17 15:33:04 +02:00
|
|
|
Feel free to open issue if you missing some configuration or customisation option.
|
2018-09-13 18:07:55 +02:00
|
|
|
|
|
|
|
|
## License
|
2018-10-31 13:12:01 +01:00
|
|
|
[MIT](LICENSE)
|
