Hugo 主题
Hugo 图书主题
Hugo 文档主题,简单如纸质书
- 功能
- 要求
- 安装
- 菜单
- 博客
- 配置
- 短代码
- 版本控制
- 贡献
功能
- 简洁的设计
- 轻量且移动设备友好
- 多语言支持
- 可自定义
- 零初始配置
- 方便的短代码
- 评论支持
- 简单的博客和分类
- 主要功能无需 JavaScript 即可工作
- 暗黑模式
要求
- Hugo 0.134 或更高版本
- 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
示例。
# (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.com.cn/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 {{< relref >}} 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 的多语言模式,只需按照那里的配置指南进行操作即可。你还可以在 i18n
文件夹中调整每种语言的搜索索引配置。
页面配置
你可以在各个页面的 front matter 中指定其他参数
# 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 = ''
局部模板
在 layouts/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 | 用自定义字体替换默认字体(例如,本地文件或像 google fonts 这样的远程字体) |
assets/mermaid.json | 替换 Mermaid 初始化配置 |
插件
有一些功能是以可插拔的 scss
样式实现的。通常这些是不会进入核心但仍然有用的功能。
插件 | 描述 |
---|---|
assets/plugins/_numbered.scss | 使 Markdown 中的标题编号,例如 1.1 、1.2 |
assets/plugins/_scrollbars.scss | 覆盖滚动条样式,使其在不同平台上看起来相似 |
要启用插件,请将 @import "plugins/{name}";
添加到您网站根目录下的 assets/_custom.scss
中。
Hugo 内部模板
有一些 Hugo 模板被插入到 <head>
中
- Google Analytics
- Open Graph
要禁用 Open Graph 的包含,您可以创建自己的空文件 \layouts\_internal\opengraph.html
。实际上几乎为空,但并不完全为空,因为空文件对于 HUGO 来说看起来是缺失的。例如
<!-- -->
简码
- 按钮
- 列
- 详情
- 提示
- KaTeX
- Mermaid
- 标签页
默认情况下,Goldmark 会修剪不安全的输出,这可能会阻止某些简码呈现。如果遇到问题,建议将 markup.goldmark.renderer.unsafe=true
设置为 true。
[markup.goldmark.renderer]
unsafe = true
如果您使用的是 config.yaml
或 config.json
,请查阅配置标记
版本控制
此主题遵循简单的增量版本控制。例如 v1
、v2
等。不同版本之间可能存在重大更改。
如果您想要较低的维护成本,请使用已发布的版本之一。如果您想使用最新的更改,可以使用 master
分支并在需要时更新您的网站。
贡献
特别感谢贡献者
欢迎贡献,我会审查并考虑 pull request。
主要目标是
- 保持简单。
- 保持最少(或零)默认配置。
- 避免干扰用户定义的布局。
- 如果可以通过 CSS 解决,则避免使用 JS。
如果您发现缺少配置或自定义选项,请随时提出 issue。