/ README.md
README.md
1 # Hugo Book Theme 2 3 [](https://gohugo.io) 4 [](LICENSE) 5  6 7 ### [Hugo](https://gohugo.io) documentation theme as simple as plain book 8 9  10 11 - [Features](#features) 12 - [Requirements](#requirements) 13 - [Installation](#installation) 14 - [Menu](#menu) 15 - [Blog](#blog) 16 - [Configuration](#configuration) 17 - [Shortcodes](#shortcodes) 18 - [Versioning](#versioning) 19 - [Contributing](#contributing) 20 21 ## Features 22 23 - Clean simple design 24 - Light and Mobile-Friendly 25 - Multi-language support 26 - Customisable 27 - Zero initial configuration 28 - Handy shortcodes 29 - Comments support 30 - Simple blog and taxonomy 31 - Primary features work without JavaScript 32 - Dark Mode 33 34 ## Requirements 35 36 - Hugo 0.134 or higher 37 - Hugo extended version, [Installation Instructions](https://gohugo.io/installation/) 38 39 ## Installation 40 41 ### Install as git submodule 42 Navigate to your hugo project root and run: 43 44 ``` 45 git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book 46 ``` 47 48 Then run hugo (or set `theme = "hugo-book"`/`theme: hugo-book` in configuration file) 49 50 ``` 51 hugo server --minify --theme hugo-book 52 ``` 53 54 ### Install as hugo module 55 56 You can also add this theme as a Hugo module instead of a git submodule. 57 58 Start with initializing hugo modules, if not done yet: 59 ``` 60 hugo mod init github.com/repo/path 61 ``` 62 63 Navigate to your hugo project root and add [module] section to your `hugo.toml`: 64 65 ```toml 66 [module] 67 [[module.imports]] 68 path = 'github.com/alex-shpak/hugo-book' 69 ``` 70 71 Then, to load/update the theme module and run hugo: 72 73 ```sh 74 hugo mod get -u 75 hugo server --minify 76 ``` 77 78 ### Creating site from scratch 79 80 Below is an example on how to create a new site from scratch: 81 82 ```sh 83 hugo new site mydocs; cd mydocs 84 git init 85 git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book 86 cp -R themes/hugo-book/exampleSite/content.en/* ./content 87 ``` 88 89 ```sh 90 hugo server --minify --theme hugo-book 91 ``` 92 93 ## Menu 94 95 By default, the theme will render pages from the `content/docs` section as a menu in a tree structure. 96 You can set `title` and `weight` in the front matter of pages to adjust the order and titles in the menu, as well as other parameters to hide or alter urls in the menu. You can choose which folder to use for generating menu with `BookSection` configuration parameter. 97 98 ## Blog 99 100 A simple blog is supported in the section `posts`. 101 A blog is not the primary usecase of this theme, so it has only minimal features. 102 103 ## Configuration 104 105 ### Site Configuration 106 107 There are a few configuration options that you can add to your `hugo.toml` file. 108 You can also see the `yaml` example [here](https://github.com/alex-shpak/hugo-book/blob/master/exampleSite/hugo.yaml). 109 110 ```toml 111 # (Optional) Set Google Analytics if you use it to track your website. 112 # Always put it on the top of the configuration file, otherwise it won't work 113 googleAnalytics = "UA-XXXXXXXXX-X" 114 115 # (Optional) If you provide a Disqus shortname, comments will be enabled on 116 # all pages. 117 disqusShortname = "my-site" 118 119 # (Optional) Set this to true if you use capital letters in file names 120 disablePathToLower = true 121 122 # (Optional) Set this to true to enable 'Last Modified by' date and git author 123 # information on 'doc' type pages. 124 enableGitInfo = true 125 126 # (Optional) Theme is intended for documentation use, therefore it doesn't render taxonomy. 127 # You can remove related files with config below 128 disableKinds = ['taxonomy', 'taxonomyTerm'] 129 130 [params] 131 # (Optional, default light) Sets color theme: light, dark or auto. 132 # Theme 'auto' switches between dark and light modes based on browser/os preferences 133 BookTheme = 'light' 134 135 # (Optional, default true) Controls table of contents visibility on right side of pages. 136 # Start and end levels can be controlled with markup.tableOfContents setting. 137 # You can also specify this parameter per page in front matter. 138 BookToC = true 139 140 # (Optional, default none) Set the path to a logo for the book. If the logo is 141 # /static/logo.png then the path would be 'logo.png' 142 BookLogo = 'logo.png' 143 144 # (Optional, default docs) Specify section of content to render as menu 145 # You can also set value to "*" to render all sections to menu 146 BookSection = 'docs' 147 148 # Set source repository location. 149 # Used for 'Last Modified' and 'Edit this page' links. 150 BookRepo = 'https://github.com/alex-shpak/hugo-book' 151 152 # Specifies commit portion of the link to the page's last modified commit hash for 'doc' page 153 # type. 154 # Required if 'BookRepo' param is set. 155 # Value used to construct a URL consisting of BookRepo/BookCommitPath/<commit-hash> 156 # Github uses 'commit', Bitbucket uses 'commits' 157 BookCommitPath = 'commit' 158 159 # Enable 'Edit this page' links for 'doc' page type. 160 # Disabled by default. Uncomment to enable. Requires 'BookRepo' param. 161 # Path must point to the site directory. 162 BookEditPath = 'edit/master/exampleSite' 163 164 # (Optional, default January 2, 2006) Configure the date format used on the pages 165 # - In git information 166 # - In blog posts 167 BookDateFormat = 'Jan 2, 2006' 168 169 # (Optional, default true) Enables search function with flexsearch, 170 # Index is built on fly, therefore it might slowdown your website. 171 # Configuration for indexing can be adjusted in i18n folder per language. 172 BookSearch = true 173 174 # (Optional, default true) Enables comments template on pages 175 # By default partials/docs/comments.html includes Disqus template 176 # See https://gohugo.io/content-management/comments/#configure-disqus 177 # Can be overwritten by same param in page frontmatter 178 BookComments = true 179 180 # /!\ This is an experimental feature, might be removed or changed at any time 181 # (Optional, experimental, default false) Enables portable links and link checks in markdown pages. 182 # Portable links meant to work with text editors and let you write markdown without {{< relref >}} shortcode 183 # Theme will print warning if page referenced in markdown does not exists. 184 BookPortableLinks = true 185 186 # /!\ This is an experimental feature, might be removed or changed at any time 187 # (Optional, experimental, default false) Enables service worker that caches visited pages and resources for offline use. 188 BookServiceWorker = true 189 ``` 190 191 ### Multi-Language Support 192 193 Theme supports Hugo's [multilingual mode](https://gohugo.io/content-management/multilingual/), just follow configuration guide there. You can also tweak search indexing configuration per language in `i18n` folder. 194 195 ### Page Configuration 196 197 You can specify additional params in the front matter of individual pages: 198 199 ```toml 200 # Set type to 'docs' if you want to render page outside of configured section or if you render section other than 'docs' 201 type = 'docs' 202 203 # Set page weight to re-arrange items in file-tree menu. 204 weight = 10 205 206 # (Optional) Set to 'true' to mark page as flat section in file-tree menu. 207 bookFlatSection = false 208 209 # (Optional) Set to hide nested sections or pages at that level. Works only with file-tree menu mode 210 bookCollapseSection = true 211 212 # (Optional) Set true to hide page or section from side menu. 213 bookHidden = false 214 215 # (Optional) Set 'false' to hide ToC from page 216 bookToC = true 217 218 # (Optional) If you have enabled BookComments for the site, you can disable it for specific pages. 219 bookComments = true 220 221 # (Optional) Set to 'false' to exclude page from search index. 222 bookSearchExclude = true 223 224 # (Optional) Set explicit href attribute for this page in a menu. 225 bookHref = '' 226 ``` 227 228 ### Partials 229 230 There are layout partials available for you to easily override components of the theme in `layouts/partials/`. 231 232 In addition to this, there are several empty partials you can override to easily add/inject code. 233 234 | Empty Partial | Placement | 235 | -------------------------------------------------- | ------------------------------------------- | 236 | `layouts/partials/docs/inject/head.html` | Before closing `<head>` tag | 237 | `layouts/partials/docs/inject/body.html` | Before closing `<body>` tag | 238 | `layouts/partials/docs/inject/footer.html` | After page footer content | 239 | `layouts/partials/docs/inject/menu-before.html` | At the beginning of `<nav>` menu block | 240 | `layouts/partials/docs/inject/menu-after.html` | At the end of `<nav>` menu block | 241 | `layouts/partials/docs/inject/content-before.html` | Before page content | 242 | `layouts/partials/docs/inject/content-after.html` | After page content | 243 | `layouts/partials/docs/inject/toc-before.html` | At the beginning of table of contents block | 244 | `layouts/partials/docs/inject/toc-after.html` | At the end of table of contents block | 245 246 ### Extra Customisation 247 248 | File | Description | 249 | ------------------------ | ------------------------------------------------------------------------------------- | 250 | `static/favicon.png` | Override default favicon | 251 | `assets/_custom.scss` | Customise or override scss styles | 252 | `assets/_variables.scss` | Override default SCSS variables | 253 | `assets/_fonts.scss` | Replace default font with custom fonts (e.g. local files or remote like google fonts) | 254 | `assets/mermaid.json` | Replace Mermaid initialization config | 255 256 ### Plugins 257 258 There are a few features implemented as pluggable `scss` styles. Usually these are features that don't make it to the core but can still be useful. 259 260 | Plugin | Description | 261 | --------------------------------- | ----------------------------------------------------------- | 262 | `assets/plugins/_numbered.scss` | Makes headings in markdown numbered, e.g. `1.1`, `1.2` | 263 | `assets/plugins/_scrollbars.scss` | Overrides scrollbar styles to look similar across platforms | 264 265 To enable plugins, add `@import "plugins/{name}";` to `assets/_custom.scss` in your website root. 266 267 ### Hugo Internal Templates 268 269 There are a few hugo templates inserted in `<head>` 270 271 - [Google Analytics](https://gohugo.io/templates/internal/#google-analytics) 272 - [Open Graph](https://gohugo.io/templates/internal/#open-graph) 273 274 To disable Open Graph inclusion you can create your own empty file `\layouts\_internal\opengraph.html`. 275 In fact almost empty not quite empty because an empty file looks like absent for HUGO. For example: 276 ``` 277 <!-- --> 278 ``` 279 280 ## Shortcodes 281 282 - [Buttons](https://hugo-book-demo.netlify.app/docs/shortcodes/buttons/) 283 - [Columns](https://hugo-book-demo.netlify.app/docs/shortcodes/columns/) 284 - [Details](https://hugo-book-demo.netlify.app/docs/shortcodes/details/) 285 - [Hints](https://hugo-book-demo.netlify.app/docs/shortcodes/hints/) 286 - [KaTeX](https://hugo-book-demo.netlify.app/docs/shortcodes/katex/) 287 - [Mermaid](https://hugo-book-demo.netlify.app/docs/shortcodes/mermaid/) 288 - [Tabs](https://hugo-book-demo.netlify.app/docs/shortcodes/tabs/) 289 290 By default, Goldmark trims unsafe outputs which might prevent some shortcodes from rendering. It is recommended to set `markup.goldmark.renderer.unsafe=true` if you encounter problems. 291 292 ```toml 293 [markup.goldmark.renderer] 294 unsafe = true 295 ``` 296 297 If you are using `config.yaml` or `config.json`, consult the [configuration markup](https://gohugo.io/getting-started/configuration-markup/) 298 299 ## Versioning 300 301 This theme follows a simple incremental versioning. e.g. `v1`, `v2` and so on. There might be breaking changes between versions. 302 303 If you want lower maintenance, use one of the released versions. If you want to live on the bleeding edge of changes, you can use the `master` branch and update your website when needed. 304 305 ## Contributing 306 307 ### [Extra credits to contributors](https://github.com/alex-shpak/hugo-book/graphs/contributors) 308 309 Contributions are welcome and I will review and consider pull requests. 310 Primary goals are: 311 312 - Keep it simple. 313 - Keep minimal (or zero) default configuration. 314 - Avoid interference with user-defined layouts. 315 - Avoid using JS if it can be solved by CSS. 316 317 Feel free to open issues if you find missing configuration or customisation options.