hugo-book
Code Issues

Update readme with main branch, update config examples (#771)

Browse Source
This commit is contained in:
nick n.
2025-10-06 23:33:32 +02:00
committed by GitHub
parent 7fe158c8ed
commit 0593f02604
7 changed files with 33 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+6 -6
View File
@@ -6,7 +6,7 @@
### [Hugo](https://gohugo.io) documentation theme as simple as plain book ### [Hugo](https://gohugo.io) documentation theme as simple as plain book
![Screenshot](https://raw.githubusercontent.com/alex-shpak/hugo-book/master/images/screenshot.png) ![Screenshot](https://raw.githubusercontent.com/alex-shpak/hugo-book/main/images/screenshot.png)
- [Features](#features) - [Features](#features)
- [Requirements](#requirements) - [Requirements](#requirements)
@@ -105,7 +105,7 @@ A blog is not the primary usecase of this theme, so it has only minimal features
### Site Configuration ### Site Configuration
There are a few configuration options that you can add to your `hugo.toml` file. There are a few configuration options that you can add to your `hugo.toml` file.
You can also see the `yaml` example [here](https://github.com/alex-shpak/hugo-book/blob/master/exampleSite/hugo.yaml). You can also see the `yaml` example [here](https://github.com/alex-shpak/hugo-book/blob/main/exampleSite/hugo.yaml).
```toml ```toml
# (Optional) Set Google Analytics if you use it to track your website. # (Optional) Set Google Analytics if you use it to track your website.
@@ -272,10 +272,10 @@ To enable plugins, add `@import "plugins/{name}";` to `assets/_custom.scss` in y
There are a few hugo templates inserted in `<head>` There are a few hugo templates inserted in `<head>`
- [Google Analytics](https://gohugo.io/templates/internal/#google-analytics) - [Google Analytics](https://gohugo.io/templates/embedded/#google-analytics)
- [Open Graph](https://gohugo.io/templates/internal/#open-graph) - [Open Graph](https://gohugo.io/templates/embedded/#open-graph)
To disable Open Graph inclusion you can create your own empty file `/layouts/_internal/opengraph.html`. To disable Open Graph inclusion you can create your own empty file `/layouts/partials/opengraph.html`.
In fact almost empty not quite empty because an empty file looks like absent for HUGO. For example: In fact almost empty not quite empty because an empty file looks like absent for HUGO. For example:
``` ```
<!-- --> <!-- -->
@@ -304,7 +304,7 @@ If you are using `config.yaml` or `config.json`, consult the [configuration mark
This theme follows a simple incremental versioning. e.g. `v1.0.0`, `v2.0.0` and so on. Releases will happen on breaking changes. This theme follows a simple incremental versioning. e.g. `v1.0.0`, `v2.0.0` and so on. Releases will happen on breaking changes.
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. 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 `main` branch and update your website when needed, this also the default branch.
## Contributing ## Contributing
exampleSite/hugo.toml
+12 -5
View File
@@ -1,5 +1,9 @@
# hugo server --minify --themesDir ../.. # hugo server --minify --themesDir ../..
# for maximum cleanups and rebuilds, run where you checked out the repository
# hugo server --printPathWarnings --disableFastRender --cleanDestinationDir=true --logLevel=debug \
# --gc -M -s exampleSite --themesDir ../.. -b http://127.0.0.1/
baseURL = 'http://0.0.0.0:1313/hugo-book/' baseURL = 'http://0.0.0.0:1313/hugo-book/'
title = 'Hugo Book' title = 'Hugo Book'
theme = 'hugo-book' theme = 'hugo-book'
@@ -86,7 +90,7 @@ enableGitInfo = true
BookTheme = 'light' BookTheme = 'light'
# (Optional, default none) Controls table of contents visibility on right side of pages. # (Optional, default none) Controls table of contents visibility on right side of pages.
# Start and end levels can be controlled with markup.tableOfContents setting. # Start and end levels can be controlled globally with markup.tableOfContents setting.
# You can also specify this parameter per page in front matter. # You can also specify this parameter per page in front matter.
# BookToC = true # BookToC = true
@@ -103,7 +107,8 @@ enableGitInfo = true
# For backward compatibility you can set '*' to render all sections to menu. Acts same as '/' # For backward compatibility you can set '*' to render all sections to menu. Acts same as '/'
BookSection = 'docs' BookSection = 'docs'
# Here for backwar compatibility, not required. # Here for backward compatibility, not required.
# It's here as an example how to use it with BookLastChangeLink or BookEditLink
BookRepo = 'https://github.com/alex-shpak/hugo-book/' BookRepo = 'https://github.com/alex-shpak/hugo-book/'
# (Optional, default none) Set template for commit link for the page. Requires enableGitInfo. # (Optional, default none) Set template for commit link for the page. Requires enableGitInfo.
@@ -128,7 +133,7 @@ enableGitInfo = true
BookSearch = true BookSearch = true
# (Optional, default true) Enables comments template on pages # (Optional, default true) Enables comments template on pages
# By default partals/docs/comments.html includes Disqus template # By default partials/docs/comments.html includes Disqus template
# See https://gohugo.io/content-management/comments/#configure-disqus # See https://gohugo.io/content-management/comments/#configure-disqus
# Can be overwritten by same param in page frontmatter # Can be overwritten by same param in page frontmatter
BookComments = true BookComments = true
@@ -136,12 +141,14 @@ enableGitInfo = true
# /!\ This is an experimental feature, might be removed or changed at any time # /!\ This is an experimental feature, might be removed or changed at any time
# (Optional, experimental, default false) Enables portable links and link checks in markdown pages. # (Optional, experimental, default false) Enables portable links and link checks in markdown pages.
# Portable links meant to work with text editors and let you write markdown without {{< relref >}} shortcode # Portable links meant to work with text editors and let you write markdown without {{< relref >}} shortcode
# Theme will print warning or error if page referenced in markdown does not exists. # Hugo Book will print warning or error if page referenced in markdown does not exists.
# Possible values are false | 'warning' | 'error' # Possible values are false | 'warning' | 'error'
BookPortableLinks = 'warning' BookPortableLinks = 'warning'
# /!\ This is an experimental feature, might be removed or changed at any time # /!\ This is an experimental feature, might be removed or changed at any time
# (Optional, experimental, default false) Enables service worker that caches visited pages and resources for offline use. # (Optional, experimental, default false)
# When set to 'preache' it enables a service worker that caches visited pages and resources for offline use.
# Possible values are false | true | 'precache'
BookServiceWorker = 'precache' BookServiceWorker = 'precache'
# /!\ This is an experimental feature, might be removed or changed at any time # /!\ This is an experimental feature, might be removed or changed at any time
exampleSite/hugo.yaml
+10 -5
View File
@@ -1,5 +1,9 @@
# hugo server --minify --themesDir ../.. # hugo server --minify --themesDir ../..
# for maximum cleanups and rebuilds, run where you checked out the repository
# hugo server --printPathWarnings --disableFastRender --cleanDestinationDir=true --logLevel=debug \
# --gc -M -s exampleSite --themesDir ../.. -b http://127.0.0.1/
baseURL: http://0.0.0.0:1313/hugo-book/ baseURL: http://0.0.0.0:1313/hugo-book/
title: Hugo Book title: Hugo Book
theme: hugo-book theme: hugo-book
@@ -73,7 +77,7 @@ params:
BookTheme: "light" BookTheme: "light"
# (Optional, default none) Controls table of contents visibility on right side of pages. # (Optional, default none) Controls table of contents visibility on right side of pages.
# Start and end levels can be controlled with markup.tableOfContents setting. # Start and end levels can be controlled globally with markup.tableOfContents setting.
# You can also specify this parameter per page in front matter. # You can also specify this parameter per page in front matter.
# BookToC: true # BookToC: true
@@ -112,7 +116,7 @@ params:
BookSearch: true BookSearch: true
# (Optional, default true) Enables comments template on pages # (Optional, default true) Enables comments template on pages
# By default partals/docs/comments.html includes Disqus template # By default partials/docs/comments.html includes Disqus template
# See https://gohugo.io/content-management/comments/#configure-disqus # See https://gohugo.io/content-management/comments/#configure-disqus
# Can be overwritten by same param in page frontmatter # Can be overwritten by same param in page frontmatter
BookComments: true BookComments: true
@@ -120,13 +124,14 @@ params:
# /!\ This is an experimental feature, might be removed or changed at any time # /!\ This is an experimental feature, might be removed or changed at any time
# (Optional, experimental, default false) Enables portable links and link checks in markdown pages. # (Optional, experimental, default false) Enables portable links and link checks in markdown pages.
# Portable links meant to work with text editors and let you write markdown without {{< relref >}} shortcode # Portable links meant to work with text editors and let you write markdown without {{< relref >}} shortcode
# Theme will print warning or error if page referenced in markdown does not exists. # Hugo Book will print warning or error if page referenced in markdown does not exists.
# Possible values are false | 'warning' | 'error' # Possible values are false | 'warning' | 'error'
BookPortableLinks: 'warning' BookPortableLinks: 'warning'
# /!\ This is an experimental feature, might be removed or changed at any time # /!\ This is an experimental feature, might be removed or changed at any time
# (Optional, experimental, default false) Enables service worker that caches visited pages and resources for offline use. # (Optional, experimental, default false)
# can be false, true or 'precache', precache will try to download all content pages on install. # When set to 'preache' it enables a service worker that caches visited pages and resources for offline use.
# Possible values are false | true | 'precache'
BookServiceWorker: "precache" BookServiceWorker: "precache"
# /!\ This is an experimental feature, might be removed or changed at any time # /!\ This is an experimental feature, might be removed or changed at any time
layouts/_partials/docs/comments.html
+1 -1
View File
@@ -1,2 +1,2 @@
<!-- This partial can be replaced to support other commenting engines --> <!-- This partial can be replaced to support other commenting engines -->
{{ template "_internal/disqus.html" . }} {{ partial "disqus.html" . }}
layouts/_partials/docs/html-head.html
+2 -2
View File
@@ -14,7 +14,7 @@ https://github.com/alex-shpak/hugo-book
<meta http-equiv="Refresh" content="0; url='{{ . }}'" /> <meta http-equiv="Refresh" content="0; url='{{ . }}'" />
{{- end -}} {{- end -}}
{{- template "_internal/opengraph.html" . -}} {{ partial "opengraph.html" . }}
<title>{{ partial "docs/html-head-title" . }}</title> <title>{{ partial "docs/html-head-title" . }}</title>
{{ partial "docs/html-head-favicon" . }} {{ partial "docs/html-head-favicon" . }}
@@ -45,7 +45,7 @@ https://github.com/alex-shpak/hugo-book
<script defer src="{{ $swJS.RelPermalink }}" {{ template "integrity" $swJS }}></script> <script defer src="{{ $swJS.RelPermalink }}" {{ template "integrity" $swJS }}></script>
{{ end -}} {{ end -}}
{{- template "_internal/google_analytics.html" . -}} {{ partial "google_analytics.html" . }}
<!-- RSS --> <!-- RSS -->
{{- with .OutputFormats.Get "rss" -}} {{- with .OutputFormats.Get "rss" -}}
layouts/term.html
+1 -1
View File
@@ -11,7 +11,7 @@
</article> </article>
{{ end }} {{ end }}
{{ template "_internal/pagination.html" . }} {{ partial "pagination.html" . }}
{{ end }} {{ end }}
{{ define "toc-container" }} {{ define "toc-container" }}
theme.toml
+1 -1
View File
@@ -3,7 +3,7 @@
name = "Book" name = "Book"
license = "MIT" license = "MIT"
licenselink = "https://github.com/alex-shpak/hugo-book/blob/master/LICENSE" licenselink = "https://github.com/alex-shpak/hugo-book/blob/main/LICENSE"
description = "Hugo documentation theme as simple as plain book" description = "Hugo documentation theme as simple as plain book"
homepage = "https://github.com/alex-shpak/hugo-book" homepage = "https://github.com/alex-shpak/hugo-book"
demosite = "https://hugo-book-demo.netlify.app" demosite = "https://hugo-book-demo.netlify.app"