Hugo Book主题
像普通书本一样的Hugo文档主题
特性
- 干净简单的设计
- 轻便且适合移动设备
- 多语言支持
- 可定制
- 零初始配置
- 方便的短代码
- 评论支持
- 简单的博客和分类法
- 主要功能无需 JavaScript 即可工作
- 深色模式
必备条件
- Hugo 0.146以及更高版本
- Hugo 扩展版本, 安装方法
安装主题
git模块安装
在hugo工程目录下运行:
git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book
运行hugo (或者在配置文件中写入theme = "hugo-book"
/theme: hugo-book
)
hugo server --minify --theme hugo-book
hugo模块安装
您还可以将此主题添加为 Hugo 模块而不是 git 子模块。
从初始化 hugo 模块开始:
hugo mod init github.com/repo/path
进入 hugo项目根目录,并将 [module] 部分添加到你的配置文件hugo.toml
中:
[module]
[[module.imports]]
path = 'github.com/alex-shpak/hugo-book'
然后,加载/更新主题模块并运行 hugo:
hugo mod get -u
hugo server --minify
从头开始创建站点
以下是如何从头开始创建新站点的示例:
hugo new site mydocs; cd mydocs
git init
git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book
cp -R themes/hugo-book/exampleSite/content.en/* ./content
hugo server --minify --theme hugo-book
菜单
默认情况下,主题会将content/docs
中的页面呈现为树结构中的菜单。
您可以在页面的front matter
中设置title
和weight
,以调整菜单中的顺序和标题,以及用于隐藏或更改菜单中url
的其他参数。您可以使用BookSection
配置参数选择用于生成菜单的文件夹。
博客
从posts
可以生成一个简单的博客。
博客不是此主题的主要用例,因此它只有最少的功能。
配置
站点配置
There are a few configuration options that you can add to your hugo.toml
file.
You can also see the yaml
example here.
# (Optional) Set Google Analytics if you use it to track your website.
# Always put it on the top of the configuration file, otherwise it won't work
googleAnalytics = "UA-XXXXXXXXX-X"
# (Optional) If you provide a Disqus shortname, comments will be enabled on
# all pages.
disqusShortname = "my-site"
# (Optional) Set this to true if you use capital letters in file names
disablePathToLower = true
# (Optional) Set this to true to enable 'Last Modified by' date and git author
# information on 'doc' type pages.
enableGitInfo = true
# (Optional) Theme is intended for documentation use, therefore it doesn't render taxonomy.
# You can remove related files with config below
disableKinds = ['taxonomy', 'taxonomyTerm']
[params]
# (Optional, default light) Sets color theme: light, dark or auto.
# Theme 'auto' switches between dark and light modes based on browser/os preferences
BookTheme = 'light'
# (Optional, default true) Controls table of contents visibility on right side of pages.
# Start and end levels can be controlled with markup.tableOfContents setting.
# You can also specify this parameter per page in front matter.
BookToC = true
# (Optional, default none) Set the path to a logo for the book. If the logo is
# /static/logo.png then the path would be 'logo.png'
BookLogo = 'logo.png'
# (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'
# Set source repository location.
# Used for 'Last Modified' and 'Edit this page' links.
BookRepo = 'https://github.com/alex-shpak/hugo-book'
# Specifies commit portion of the link to the page's last modified commit hash for 'doc' page
# type.
# Required if 'BookRepo' param is set.
# Value used to construct a URL consisting of BookRepo/BookCommitPath/<commit-hash>
# Github uses 'commit', Bitbucket uses 'commits'
BookCommitPath = 'commit'
# Enable 'Edit this page' links for 'doc' page type.
# Disabled by default. Uncomment to enable. Requires 'BookRepo' param.
# Path must point to the site directory.
BookEditPath = 'edit/master/exampleSite'
# (Optional, default January 2, 2006) Configure the date format used on the pages
# - In git information
# - In blog posts
BookDateFormat = 'Jan 2, 2006'
# (Optional, default true) Enables search function with flexsearch,
# Index is built on fly, therefore it might slowdown your website.
# Configuration for indexing can be adjusted in i18n folder per language.
BookSearch = true
# (Optional, default true) Enables comments template on pages
# By default partials/docs/comments.html includes Disqus template
# See https://gohugo.io/content-management/comments/#configure-disqus
# Can be overwritten by same param in page frontmatter
BookComments = true
# /!\ 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.
# Portable links meant to work with text editors and let you write markdown without shortcode
# Theme will print warning if page referenced in markdown does not exists.
BookPortableLinks = true
# /!\ 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.
BookServiceWorker = true
Multi-Language Support
Theme supports Hugo’s multilingual mode, just follow configuration guide there. You can also tweak search indexing configuration per language in i18n
folder.
Page Configuration
You can specify additional params in the front matter of individual pages:
# 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.
weight = 10
# (Optional) Set to 'true' to mark page as flat section in file-tree menu.
bookFlatSection = false
# (Optional) Set to hide nested sections or pages at that level. Works only with file-tree menu mode
bookCollapseSection = true
# (Optional) Set true to hide page or section from side menu.
bookHidden = false
# (Optional) Set 'false' to hide ToC from page
bookToC = true
# (Optional) If you have enabled BookComments for the site, you can disable it for specific pages.
bookComments = true
# (Optional) Set to 'false' to exclude page from search index.
bookSearchExclude = true
# (Optional) Set explicit href attribute for this page in a menu.
bookHref = ''
Partials
There are layout partials available for you to easily override components of the theme in layouts/partials/
.
In addition to this, there are several empty partials you can override to easily add/inject code.
Empty 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/footer.html | After page footer content |
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 |
layouts/partials/docs/inject/content-before.html | Before page content |
layouts/partials/docs/inject/content-after.html | After page content |
layouts/partials/docs/inject/toc-before.html | At the beginning of table of contents block |
layouts/partials/docs/inject/toc-after.html | At the end of table of contents block |
Extra Customisation
File | Description |
---|---|
static/favicon.png | Override default favicon |
assets/_custom.scss | Customise or override scss styles |
assets/_variables.scss | Override default SCSS variables |
assets/_fonts.scss | Replace default font with custom fonts (e.g. local files or remote like google fonts) |
assets/mermaid.json | Replace Mermaid initialization config |
Plugins
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.
Plugin | Description |
---|---|
assets/plugins/_numbered.scss | Makes headings in markdown numbered, e.g. 1.1 , 1.2 |
assets/plugins/_scrollbars.scss | Overrides scrollbar styles to look similar across platforms |
To enable plugins, add @import "plugins/{name}";
to assets/_custom.scss
in your website root.
Hugo Internal Templates
There are a few hugo templates inserted in <head>
To disable Open Graph inclusion you can create your own empty file \layouts\_internal\opengraph.html
.
In fact almost empty not quite empty because an empty file looks like absent for HUGO. For example:
<!-- -->
短代码
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.
[markup.goldmark.renderer]
unsafe = true
If you are using config.yaml
or config.json
, consult the configuration markup
Versioning
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.
Contributing
Extra credits to contributors
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.
- Avoid using JS if it can be solved by CSS.
Feel free to open issues if you find missing configuration or customisation options.