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可以生成一个简单的博客。 博客不是此主题的主要用例,因此它只有最少的功能。

配置

站点配置

There are a few configuration options that you can add to your hugo.toml file.
You can also see the yaml example here.

TOML
# (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:

TOML
# 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 PartialPlacement
layouts/partials/docs/inject/head.htmlBefore closing <head> tag
layouts/partials/docs/inject/body.htmlBefore closing <body> tag
layouts/partials/docs/inject/footer.htmlAfter page footer content
layouts/partials/docs/inject/menu-before.htmlAt the beginning of <nav> menu block
layouts/partials/docs/inject/menu-after.htmlAt the end of <nav> menu block
layouts/partials/docs/inject/content-before.htmlBefore page content
layouts/partials/docs/inject/content-after.htmlAfter page content
layouts/partials/docs/inject/toc-before.htmlAt the beginning of table of contents block
layouts/partials/docs/inject/toc-after.htmlAt the end of table of contents block

Extra Customisation

FileDescription
static/favicon.pngOverride default favicon
assets/_custom.scssCustomise or override scss styles
assets/_variables.scssOverride default SCSS variables
assets/_fonts.scssReplace default font with custom fonts (e.g. local files or remote like google fonts)
assets/mermaid.jsonReplace 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.

PluginDescription
assets/plugins/_numbered.scssMakes headings in markdown numbered, e.g. 1.1, 1.2
assets/plugins/_scrollbars.scssOverrides 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:

PLAINTEXT
<!-- -->
点击展开查看更多

短代码

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.

TOML
[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:

Feel free to open issues if you find missing configuration or customisation options.

版权声明

作者: 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 快捷键