Hugo Book主题

像普通书本一样的Hugo文档主题

Hugo文档主题

特性

必备条件

安装主题

git模块安装

在hugo工程目录下运行:

PLAINTEXT
git submodule add https://github.com/alex-shpak/hugo-book themes/hugo-book
点击展开查看更多

运行hugo (或者在配置文件中写入theme = "hugo-book"/theme: hugo-book)

PLAINTEXT
hugo server --minify --theme hugo-book
点击展开查看更多

hugo模块安装

您还可以将此主题添加为 Hugo 模块而不是 git 子模块。

从初始化 hugo 模块开始:

PLAINTEXT
hugo mod init github.com/repo/path
点击展开查看更多

进入 hugo项目根目录,并将 [module] 部分添加到你的配置文件hugo.toml中:

TOML
[module]
[[module.imports]]
path = 'github.com/alex-shpak/hugo-book'
点击展开查看更多

然后,加载/更新主题模块并运行 hugo:

SH
hugo mod get -u
hugo server --minify
点击展开查看更多

从头开始创建站点

以下是如何从头开始创建新站点的示例:

SH
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
点击展开查看更多
SH
hugo server --minify --theme hugo-book
点击展开查看更多

菜单

默认情况下,主题会将content/docs中的页面呈现为树结构中的菜单。 您可以在页面的front matter中设置titleweight,以调整菜单中的顺序和标题,以及用于隐藏或更改菜单中url的其他参数。您可以使用BookSection配置参数选择用于生成菜单的文件夹。

博客

posts可以生成一个简单的博客。 博客不是此主题的主要用例,因此它只有最少的功能。

配置

站点配置

以下时配置文件hugo.toml中的部分内容。

yaml完整示例请参照 这里

TOML
# 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中指定其他参数:

TOML
#页面类型
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 会筛选掉不安全的输出,这可能会阻止某些短代码的呈现方式。如果遇到此问题,如下设置:

TOML
[markup.goldmark.renderer]
  unsafe = true
点击展开查看更多

如果你使用的是config.yamlconfig.json, 可参阅 标记配置

版本控制

此主题遵循简单的增量版本控制。例如 ‘v1.0.0’、‘v2.0.0’ 等。发布将在重大更改时进行。

如果您想要降低维护成本,请使用其中一个已发布的版本。如果您想生活在变化的最前沿,您可以使用 ‘master’ 分支并在需要时更新您的网站。

贡献

贡献者的额外积分

欢迎贡献,我将审查和考虑拉取请求。 主要目标是:

如果您发现缺少配置或自定义选项,请随时反馈。

版权声明

作者: 0X8

链接: https://hugotheme.cn/posts/hugo-book/

许可证: CC BY-NC-SA 4.0

This work is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License. Please attribute the source, use non-commercially, and maintain the same license.

开始搜索

输入关键词搜索文章内容

↑↓
ESC
⌘K 快捷键