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 >}}
效果如下:
多列 #
多列帮助水平组织碎片化短内容。
{{% 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 >}}
KaTeX #
KaTeX 短代码允许你在markdown文中渲染数学表达式。更多内容请看KaTeX
{{< katex display=true >}}
f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi
{{< /katex >}}
这里是行内示例: \(\pi(x)\) , 在同一行中渲染。 \[ f(x) = \int_{-\infty}^\infty\hat f(\xi)\,e^{2 \pi i \xi x}\,d\xi \] 文本在这里继续。