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
可以生成一个简单的博客。
博客不是此主题的主要用例,因此它只有最少的功能。
配置
站点配置
以下时配置文件hugo.toml
中的部分内容。
yaml
完整示例请参照 这里
# Google分析代码,不设置则不生效
googleAnalytics = "UA-XXXXXXXXX-X"
# Disqus评论代码
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
多语言支持
本主题支持 Hugo多语言模块。
页面配置
您可以在各个页面的front matter
中指定其他参数:
#页面类型
type = 'docs'
# 权重
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 = ''
布局
layouts/partials/
中可存储布局文件,以根据需要进行自定义修改。
除此之外,您还可以覆盖几个空的partials
以轻松添加代码。
部分路径 | 放置位置 |
---|---|
layouts/partials/docs/inject/head.html | <head> 标记部分 |
layouts/partials/docs/inject/body.html | <body> 标记部分 |
layouts/partials/docs/inject/footer.html | 页脚部分 |
layouts/partials/docs/inject/menu-before.html | <nav> 导航开始部分 |
layouts/partials/docs/inject/menu-after.html | <nav> 导航菜单结尾 |
layouts/partials/docs/inject/content-before.html | 页面内容前 |
layouts/partials/docs/inject/content-after.html | 页面内容后 |
layouts/partials/docs/inject/toc-before.html | 目录开始部分 |
layouts/partials/docs/inject/toc-after.html | 目录结尾部分 |
额外定制
文件 | 说明 |
---|---|
static/favicon.png | 网站图标 |
assets/_custom.scss | 自定义scss样式 |
assets/_variables.scss | 覆盖默认SCSS变量 |
assets/_fonts.scss | 自定义字体设置 |
assets/mermaid.json | 替换 Mermaid 初始化配置 |
Hugo内置模板
以下是在 <head>
中插入的hugo内置模板。
想要禁用Open Graph,可以建一个空的 \layouts\_internal\opengraph.html
文件覆盖。
短代码
默认情况下,Goldmark 会筛选掉不安全的输出,这可能会阻止某些短代码的呈现方式。如果遇到此问题,如下设置:
[markup.goldmark.renderer]
unsafe = true
如果你使用的是config.yaml
或 config.json
, 可参阅 标记配置
版本控制
此主题遵循简单的增量版本控制。例如 ‘v1.0.0’、‘v2.0.0’ 等。发布将在重大更改时进行。
如果您想要降低维护成本,请使用其中一个已发布的版本。如果您想生活在变化的最前沿,您可以使用 ‘master’ 分支并在需要时更新您的网站。
贡献
贡献者的额外积分
欢迎贡献,我将审查和考虑拉取请求。 主要目标是:
- 保持简单。
- 保持最小(或零)默认配置。
- 避免干扰用户定义的布局。
- 如果 CSS 可以解决,请避免使用 JS。
如果您发现缺少配置或自定义选项,请随时反馈。