Hugo Book主题

Hugo book主题说明书 #

前言 #

如你所见,本站所用的Hugo主题为book主题,一款非常简洁的主题,不过这款主题的配置项比较多,且对文件组织结构有一定要求,也是可以深入探讨一下的。

主题的安装可以参考我的另一篇文章,假定已经安装完成了该主题。

需求 #

Hugo 0.134或更高版本的扩展版本。

站点设置 #

该主题支持部分站点设置:

    # (可选) 设置谷歌分析,如果你用它来跟踪你的网站。
    # 总是把它放在配置文件的顶层,否则它将不起作用。
    googleAnalytics = "UA-XXXXXXXXX-X"

    # (可选) 如果您提供Disqus短名称,则注释将在所有页面被启用。
    disqusShortname = "my-site"

    # (可选) 如果在文件名中使用大写字母,则将此设置为true。
    disablePathToLower = true

    # (可选) 将此设置为true以在'doc'类型页面启用包括日期和作者的'最后修改'信息。
    enableGitInfo = true

    # (可选) 主题用于文档使用,因此它不渲染taxonomy。
    #你可以在config下删除相关文件
    disableKinds = ['taxonomy', 'taxonomyTerm']

    [params]
    # (可选, 默认light) 设置颜色主题:浅色,深色或自动。
    # '自动'主题会根据浏览器/操作系统的偏好在暗模式和亮模式之间切换。
    BookTheme = 'light'

    # (可选, 默认true) 控制页面右侧的目录可见性。
    # 开始和结束级别可以用markup.tableOfContents来控制
    # 也可以在文件头中为每个页面指定此参数。
    BookToC = true

    # (可选, 默认none) 将该路径文件设置为书的徽标。如果logo是/static/logo.png则路径为'logo.png'
    BookLogo = 'logo.png'

    # (可选, 默认docs) 指定要呈现为站点目录的内容部分。您也可以设置值为"*",以渲染所有的部分到菜单
    BookSection = 'docs'

    # 设置源存储库位置,用于"上次修改"和"编辑此页"链接。
    BookRepo = 'https://github.com/alex-shpak/hugo-book'

    # 为'doc'页指定指向该页上次修改的提交散列的链接的提交部分类型。
    #如果设置了'BookRepo'参数,则必需。
    #用于构造由BookRepo/BookCommitPath/<commit-hash>组成的URL的值
    # Github使用'commit', Bitbucket使用'commits'
    BookCommitPath = 'commit'

    # 为'doc'页面类型启用"编辑此页"链接。
    # 默认禁用。取消注释以启用。需要'BookRepo'参数。
    # Path必须指向站点目录。
    BookEditPath = 'edit/master/exampleSite'

    # (可选, 默认January 2, 2006) 配置页面上使用的日期格式
    # - 在git信息中
    # - 在博客文章中
    BookDateFormat = 'Jan 2, 2006'

    # (可选, 默认true) 启用flexsearch搜索功能,
    # 索引是建立在fly,因此它可能会减慢你的网站。
    # 索引的配置可以在每个语言的i18n文件夹中进行调整。
    BookSearch = true

    # (可选, 默认true) 在页面上启用评论。
    # 默认partials/docs/comments.html包含Disqus模板。
    # 参见https://gohugo.io/content-management/comments/#configure-disqus。
    # 可以被相同的参数覆盖在文件头。
    BookComments = true

    # /!\ 这是一个实验性的功能,可能会在任何时候被删除或更改。
    # (可选,实验性的,默认为false) 在Markdown页面中启用可移植链接和链接检查。
    # 可以指链接意味着与文本编辑器一起工作,让您在没有{< relref >}短代码的情况下编写Markdown。
    如果在markdown中引用的页面不存在,主题将打印警告。
    BookPortableLinks = true

    # /!\ 这是一个实验性的功能,可能会在任何时候被删除或更改。
    # (可选,实验性的,默认为false) 启用service worker缓存访问过的页面和资源以供离线使用。
    BookServiceWorker = true

文件结构 #

hugo-book该主题对文档的组织结构有一定要求,这是本站的根目录下content目录内部分文件的组织结构。

│  _index.md
└─docs
    ├─Collection
    │      book.md
    │      script.md
    │      sigil.md
    │      website.md
    │      _index.md
    ├─Other
    │      _index.md
    ├─Project
    │      _index.md
    └─Tech
            adobe.md
            hugo-book.md
            hugo.md
            _index.md

首先在根目录下有一个_index.md文件,该文件作为整个站点的首页存在,docs下的每个文件夹都是网站左侧的目录一个标题层级,例如当前我的文件结构中存在"Collection"和"Tech"两个文件夹,对应着网站左侧目录的"快速链接"和"技术分享"两栏,如果我想要二级目录也可以在相应文件夹下继续嵌套新的文件夹,更多层级同理。

想要构成一级目录,还需要在相应层级下同样新建_index.md文件,可以进行部分配置,配置内容和正是内容大致相同,如果填写正文的话,那么目录标题同样可以作为一篇文章点击查看,如果不填写正文,目录标题仅作展示使用。

例如,这是我的快速链接全文:

---
title: "快速链接"
weight: 1
bookFlatSection: true
# bookToc: true
# bookHidden: false
# bookCollapseSection: false
# bookComments: false
bookSearchExclude: true
---

那么这个页面会在站点左侧作为"快速链接"这个标题展示,并且因为没有正文所以不能点击查看内容,和通常的标题配置额外添加了一个bookSearchExclude标签,意为从搜索中排除,即无法通过搜索索引到这个纯粹作为标题而毫无内容的页面上。

文档组织 #

默认情况下,主题会从 content/docs 目录下渲染文章结构,如果在这个位置新建Markdown文档会自动生成带有title和weight的文件头,比如新建立的这篇文章就有如下文件头:

    ---
    title: "Hugo Book主题"
    weight: 1
    # bookFlatSection: false
    # bookToc: true
    # bookHidden: false
    # bookCollapseSection: false
    # bookComments: false
    # bookSearchExclude: false
    ---

这里的title是标题栏显示的标题,权重是在左侧菜单列表中的排列权重,数字越小排序越靠前,同权重会以字符顺序排列。

下面的六个选项默认是注释状态,启用需要删除掉前面的井号,原文档对这些可选参数解释如下:

# 如果你想在配置的部分之外渲染页面,或者渲染的部分不是"docs",则将type设置为"docs"
type = 'docs'

# 设置页面权重以重新排列文件树菜单中的项目。
weight = 10

# (可选) 设置为"true"以在文件树菜单中将页面标记为flat部分。
bookFlatSection = false

# (可选) 设置隐藏该级别的嵌套部分或页面。仅适用于文件树菜单模式。
bookCollapseSection = true

# (可选) 设置为true以隐藏左侧网站侧边菜单中的页面或部分。
bookHidden = false

# (可选) 设置"false"以隐藏右侧文章内容标题索引。
bookToC = true

# (可选) 如果您已经为站点启用了评论功能,则可以对特定页面禁用它。
bookComments = true

# (可选) 设置为"false"以从搜索索引中排除页面。
bookSearchExclude = true

# (可选) 在菜单中为该页设置显式的链接属性。
bookHref = ''

短代码 #

在hugo-boook中自带七种短代码,以支持在页面中嵌入部分组件,由于默认情况下,渲染器会组织不安全的输出,因此首先需要在配置文件中加入如下设置:

[markup]
[markup.goldmark.renderer]
unsafe = true

按钮 #

按钮支持作为一种样式化的链接以链接到本地页面或者外部链接。

{{< button relref="/" [class="..."] >}}Home{{< /button >}}
{{< button href="https://github.com/" >}}Contribute{{< /button >}}

效果如下:

Home Github

多列 #

多列帮助水平组织碎片化短内容。

{{% columns [ratio="1:1"] [class="..."] %}}
#### 左内容
这里是左侧内容。

<--->

#### 中内容
这里是中间内容。

<--->

#### 右内容
这里是右侧内容。
{{% /columns %}}

结果如下:

左内容 #

这里是左侧内容。

中内容 #

这里是中间内容。

右内容 #

这里是右侧内容。

不同宽度的多列 #

{{% columns ratio="1:2" %}} 

#### 一倍宽度内容
这里是一倍宽度内容。

<---> 

#### 两倍宽度内容
这里是两倍宽度内容容容容容容容容容容。

{{% /columns %}}

一倍宽度内容 #

这里是一倍宽度内容。

两倍宽度内容 #

这里是两倍宽度内容容容容容容容容容容。

详细 #

详细短代码是html5的detiles辅助元素,覆盖了其open代码。open表示默认展开,更改为close即默认关闭。

{{% details "详细" open %}}
#### 点击展开详细内容
这里是详细内容
{{% /details %}}
详细

点击展开详细内容 #

这里是详细内容

提示 #

提示短代码作为 提示/警告/通知 代码块使用,分别由 信息/警告/危险三种颜色。

{{% hint [info|warning|danger] %}}
**内容**  
这里是内容。
{{% /hint %}}

信息
这是一条信息。

警告
这是一条警告。

危险
这是一条危险警报。

Mermaid图表(不会用这个) #

MermaidJS是一个用于从文本生成svg图表的库。

{{< mermaid [class="..."] >}}
stateDiagram-v2
    State1: 状态1
    note right of State1
        信息
    end note
    State1 --> State2
    note left of State2 : 信息.
{{< /mermaid >}}
stateDiagram-v2
    State1: 状态1
    note right of State1
        信息
    end note
    State1 --> State2
    note left of State2 : 信息.

标签栏 #

Tabs let you organize content by context, for example installation instructions for each supported platform.

{{< tabs "id" >}}
{{% tab "标签1" %}} # 标签内容1。 {{% /tab %}}
{{% tab "标签2" %}} # 标签内容2。 {{% /tab %}}
{{% tab "标签3" %}} # 标签内容3。 {{% /tab %}}
{{< /tabs >}}

MacOS #

标签内容1。

Linux #

标签内容2。

Windows #

标签内容3。

KaTeX #

KaTeX 短代码允许你在markdown文中渲染数学表达式。更多内容请看KaTeX

{{< katex display=true >}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{< /katex >}}
\[ f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi \]

这里是行内示例: \(\pi(x)\) , 在同一行中渲染。 \[ f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi \] 文本在这里继续。