一、安装

1
2
3
4
5
6
7
8
9


# 新建站点
hugo new site hugo-learn

# 进入站点路径下
cd hugo-learn

# 安装主题
cd themes
git clone https://github.com/matcornic/hugo-theme-learn.git

修改根目目下的config.toml进行简单配置：

1
2
3
4
5


baseURL = 'http://example.org/'
languageCode = 'zh'
title = '命令文档'
# 指定主题
theme = "hugo-theme-learn"

此时便可以启动了：

1

hugo server

如果一切顺利的话，启动后在1313端口便可看到页面了。

二、基本使用

首先将站点项目的archetypes/目录下的default.md文件删除，这样以后创建文章就会使用主题内的default.md模板文件了。如果主题内的模板无法满足您的需求，您可以将主题内的该文件复制到archetypes/目录下，然后对其进行定制化，这样以后创建的文章变采用您定制化后的模板文件。总结起来就是：优先使用站点的模板，如果没有站点的模板就使用主题内的模板。

1
2
3
4


# 进行站点项目内
cd hugo-learn
# 删除模板文件
rm archetypes/default.md

1. 创建一个章节

1
2


# 基于模板“chapter.md”创建文件
hugo new --kind chapter Docker/_index.md

生成的文件如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


+++
title = "Docker"
date = 2021-08-22T17:02:53+08:00
weight = 5
chapter = true
pre = "<b>X. </b>"
+++

### Chapter X

# Some Chapter title

Lorem Ipsum.

顶部配置中，有两个不常见的配置：

chapter，这个属性设置为true，是声明当前文件为章节。
pre，这个属性可以指定当前章节的名称前面的内容，例如上述配置在页面即展示为：“X. Docker”。

### Chapter X是指定章节编号，# Some Chapter title是指定章节标题，Lorem Ipsum.位置是指定章节描述信息。

例如，我们对上述文件进行如下改造：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


+++
title = "Docker"
date = 2021-08-22T17:02:53+08:00
weight = 1
chapter = true
pre = "<b>1. </b>"

+++

### 章节 1

# Docker

本章节主要讲述Docker的相关命令。

效果如下：

hugo-learn-chapter

2. 创建一个内容文件

1

hugo new Docker/common.md

生成的common.md如下所示：

1
2
3
4
5
6
7
8


+++
title = "Common"
date =  2021-08-22T17:41:14+08:00
weight = 5

+++

Lorem Ipsum.

对其进行修改：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14


+++
title = "常用命令"
date =  2021-08-22T17:41:14+08:00
weight = 1

+++

```shell
# 查看docker版本
docker -v

# 查看所有已下载镜像
docker images
```

效果如下：

hugo-learn-content

三、配置详解

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40


[params]
  # 为URL添加前缀以编辑当前页面。将在每页的右上角显示“编辑此页”按钮。
  # 有助于让人们有机会为您的文档创建合并请求。
  editURL = ""
  # 该网站的作者，将用于元信息
  author = ""
  # 该网站的说明，将用于元信息
  description = ""
  # 在菜单上显示已访问页面的复选标记，默认是false
  showVisitedLinks = false
  # 禁用搜索功能。它将隐藏搜索栏，默认是false
  disableSearch = false
  # 当生成站点的新版本时，Javascript和CSS缓存会自动被失效。
  # 将此设置为true以禁用此行为（某些代理无法很好地处理此优化）
  disableAssetsBusting = false
  # 将此设置为true可禁用行内代码的“复制到剪贴板”按钮。
  disableInlineCopyToClipBoard = false
  # 默认设置菜单中快捷方式的标题。将此设置为true以禁用它。
  disableShortcutsTitle = false
  # 如果设置为false，则在菜单上的搜索栏下方将显示Home（主页）按钮。
  # 如果指定，它将重定向到当前语言的登录页(默认值为“/”）
  disableLandingPageButton = true
  # 使用多语言网站时，禁用“切换语言”按钮。
  disableLanguageSwitchingButton = false
  # 在页眉中隐藏面包屑，仅显示当前页面标题
  disableBreadcrumb = true
  # 如果设置为true，则在不需要时阻止Hugo引入mermaid模块（将减少加载时间和流量）
  disableMermaid = false
  # 指定mermaid js的远程位置
  customMermaidURL = "https://unpkg.com/mermaid@8.8.0/dist/mermaid.min.js"
  # 隐藏下一页和上一页按钮 通常显示在内容旁边的全高位置，默认是false
  disableNextPrev = true
  # 按“weight”或“title”排列菜单中的部分。默认为“weight”，即权重
  ordersectionsby = "weight"
  # 使用变体更改默认配色方案。可以是“red”、“blue”、“green”。
  themeVariant = ""
  # 提供自定义css文件列表，以从站点根目录中的“static/”文件夹相对加载。
  custom_css = ["css/foo.css", "css/bar.css"]
  # 更改标题分隔符。默认为“::”。
  titleSeparator = "-"

四、特性的使用

1. 开启搜索

在站点配置文件中添加如下配置：

1
2


[outputs]
  home = [ "HTML", "RSS", "JSON"]

“learn”主题采用的是lunr.js检索，按照上述这样就可以搜索了，添加上述配置是为了在生成静态文件时，同时生成站点的索引文件，以便在搜索时用于检索。

2. 更换Logo

首先将主题内的logo.html复制到站点布局的目录内：

1
2
3
4
5
6


# 进入站点目录
cd hugo-learn
# 新建partials目录
mkdir layouts/partials/
# 执行复制
cp themes/hugo-theme-learn/layouts/partials/logo.html layouts/partials/

然后编辑logo.html：

1
2
3


<a id="logo" href='{{ (cond (and (ne .Site.Params.landingPageURL nil) (.Site.IsMultiLingual)) .Site.Params.landingPageURL "/") }}'>
  <!-- 此处可以是一个svg，也可以是一个图片，使用HTML语言引入即可 -->
</a>

3. 更换favicon

与更换Logo的方法一致，不同点在于本次要修改的文件是favicon.html。

首先将主题内的favicon.html复制到站点布局的目录内：

1
2
3
4
5
6


# 进入站点目录
cd hugo-learn
# 新建partials目录
mkdir layouts/partials/
# 执行复制
cp themes/hugo-theme-learn/layouts/partials/favicon.html layouts/partials/

然后编辑favicon.html：

1

<link rel="icon" href="{{"images/cmd-line.svg" | relURL}}" type="image/svg+xml">

上述设置需将cmd-line.svg文件放至static/images/目录下。

4. 创建一个首页

在content/目录下创建一个_index.md文件，内容如下：

1
2
3
4
5
6
7


---
title: "命令库"
---

# 命令库

这儿主要放一些常用的命令。

效果如图所示：

hugo-learn-index

如果想在首页展示章节目录，则可以使用短码children。

最简单的，可以像如下使用：

1

{{% children %}}

children可以指定多个参数，上述用法的各参数都取了默认值。它可设置的参数如下：

参数	默认值	描述
page	current	指定要为其显示子项的页面名称（节名称）
style	“li”	选择用于显示子项的样式。它可以是任何HTML tag名
showhidden	“false”	如果为true，将显示菜单中隐藏的子页面
description	“false”	允许您在列表中的每个子项下包含一个短文本。当页面没有描述时，`children`短码将截取内容的前70个单词。阅读更多关于gohugo.io摘要的信息。其实就是每个页面的头部中设定的`description`属性将被展示在子项的标题下方，如果未设置`description`，则截取本页面内容的70个字符。
depth	1	输入数字以指定要显示的子体的深度。例如，如果值为2，则短代码将显示两级子页面。提示：设置999以获取所有层级的子项
sort	none	可以设置四种排序方式： 1. Weight，按菜单顺序排序 2. Name，在菜单标签上按字母顺序排序 3. Identifier，根据frontmatter中设置的标识符按字母顺序排序 4. URL，根据URL排序

例如，我们使用如下短码：

1

{{% children description="true" depth="2" %}}

页面效果如下：

hugo-learn-children

可以看到，我们设定它展示两层，则Docker下的常用命令也展示出来了。除此之外还展示了每个页面的描述信息（description），而且，Docker页面我们明确指定了description，所以它展示的描述信息就是我们指定的。但是常用命令页面我们未指定description，所以此处展示的就是截取了其中部分字符串。

5. 使用短码设置提示块（notice）

有4种类型的提示可供选择：note、info、tip、warning。

使用方式为：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18


{{% notice note %}}
A notice disclaimer
{{% /notice %}}


{{% notice info %}}
An information disclaimer
{{% /notice %}}


{{% notice tip %}}
A tip disclaimer
{{% /notice %}}


{{% notice warning %}}
A warning disclaimer
{{% /notice %}}

效果如下：

hugo-learn-notice

6. 使用短码设置tab页

设置方式如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41


{{< tabs groupId="config" >}}
{{% tab name="json" %}}
```json
{
  "Hello": "World"
}
```
{{% /tab %}}
{{% tab name="XML" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{% tab name="properties" %}}
```properties
Hello = World
```
{{% /tab %}}
{{< /tabs >}}



{{< tabs groupId="config" >}}
{{% tab name="json" %}}
```json
{
  "Hello": "World"
}
```
{{% /tab %}}
{{% tab name="XML" %}}
```xml
<Hello>World</Hello>
```
{{% /tab %}}
{{% tab name="properties" %}}
```properties
Hello = World
```
{{% /tab %}}
{{< /tabs >}}

效果如下：

hugo-learn-tabs

tabs中的groupId顾名思义是用来分组的，如果两个tabs的groupId一样，则选择其中一个tab时，另一个tabs中的同名tab也会被选中。类似上述设置，则点击XML tab时，另一个tabs中的XML也会被选中。

五、美化

1. 在菜单栏的标题前展示图标

通过在Markdown文件的头部设置pre属性，即可在菜单栏中展示图标，例如：

1
2
3
4
5
6


+++
title = "Docker"
chapter = true
pre = "<i class='fab fa-docker'></i> "
description = "本章节主要讲述Docker的相关命令。"
+++

效果如下：

所有Font Awesome Gallery下的免费图标都可以使用。

如果你想用的图标在上述网站查不到，那么你也可以自己做图标。

进入IcoMoon App - Icon Font, SVG, PDF & PNG Generator：

点击“Import Icons”按钮，上传某个svg文件，上传完成后选中它，然后点击“Generate Font”：

icomoon-generate

可以修改名字为“kafka”，然后点击“download”。解压下载下来的压缩包，内容如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13


.
├── Read Me.txt
├── demo-files
│   ├── demo.css
│   └── demo.js
├── demo.html
├── fonts
│   ├── icomoon.eot
│   ├── icomoon.svg
│   ├── icomoon.ttf
│   └── icomoon.woff
├── selection.json
└── style.css

我们可以通过demo.html来看效果。

icomoon-demo

下面我们讲解如何在我们的主题中使用它。

首先把相应文件放至站点项目根目录下的static目录内，比如，我在该目录下新建了个fonts目录，然后把刚解压好的文件夹内的fonts目录及其下的文件和style.css文件放至刚新建的fonts目录内，放至好之后static目录如下：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10


.
├── fonts
│   ├── fonts
│   │   ├── icomoon.eot
│   │   ├── icomoon.svg
│   │   ├── icomoon.ttf
│   │   └── icomoon.woff
│   └── style.css
└── images
    └── cmd-line.svg

（忽略images目录，和此处所讲内容无关）

此时，我们就已经保证了在使用hugo命令生成静态文件时会把这些文件放至public目录内，下一步要做的就是让我们的页面上可以引用到它。

在站点项目的layouts/partials内新增custom-header.html，其内容如下：

1
2


{{ $assetBusting := not .Site.Params.disableAssetsBusting }}
<link href="/cmd/fonts/style.css{{ if $assetBusting }}?{{ now.Unix }}{{ end }}" rel="stylesheet">

这种方式是本主题所支持的，即在生成静态文件时，会把这个文件内的内容放至HTML文件里。此处所写的路径是绝对路径，不然在非首页内就无法取到style.css文件了。之所以此处我写了cmd，是因为我的项目部署在域名下的cmd下。

这样，我们的每个页面都引用了fonts/style.css文件了，下一步就是使用对应的图标了。

我们可以在demo.html中看到我们自定义图标的名称为icon-kafka，我们可以像上面使用“Font Awesome”的图标一样使用它：

1
2
3
4
5
6


+++
title = "常用命令"
date =  2021-08-22T17:41:14+08:00
weight = 1
pre = "<i class='icon-kafka'></i> "
+++

效果如下：

icomoon-view

当然，上述示例仅自定义了一个图标，你可以根据自己的需求一次定制多个。但是这个网站的免费账户没法保存你的项目，你只能将项目导出为json文件，然后等需要再往里面添加图标时，将该项目导入，然后再添加图标，生成并下载完成后将项目再次导出到本地保存。否则项目只会保存在你的浏览器缓存里，24小时后失效。

六、常见问题解决

1. 点击logo或home时跳转到域名根目录的问题解决

当我们在站点配置文件中设定的baseURL为https://zhdbest.github.io/cmd/时，那我们可以通过该URL访问，但是当点击logo或者home菜单时，都会跳转到https://zhdbest.github.io/。

因为我自定义了logo，所以看了logo.html文件，它是一个a标签内包含了logo元素，a标签如下：

1
2
3


<a id="logo" href='{{ (cond (and (ne .Site.Params.landingPageURL nil) (.Site.IsMultiLingual)) .Site.Params.landingPageURL "/") }}'>
  
</a>

因为我也不搞多语言，所以此处我的解决方式很暴力，就是直接把href属性设置为/cmd：

1
2
3


<a id="logo" href='/cmd'>
  
</a>

问题解决。

至于home菜单点击后跳转域名根目录的问题，我的解决方式同样暴力，直接修改配置文件，隐藏home菜单。（因为我看该主题官网都隐藏了home菜单。）

1
2


[params]
  disableLandingPageButton = true

等以后有时间了再去研究其他解决方案吧。

2. 部署后搜索失效了

在本地启动后，可以使用搜索，但是发现将网站部署至GitHub Pages之后，搜索就失效了。通过“F12”看了一下，原因是跨域造成浏览器未能加载“index.json”文件。

因为我设置的站点的baseUrl为https://zhdbest.github.io/cmd/，然后我又自定义了自己的GitHub Pages域名为hongmao.run，所以，访问本项目的URL就变成了https://hongmao.run/cmd/，但是它在加载“index.json”时使用的是https://zhdbest.github.io/cmd/域名，所以造成了跨域。

解决方案为修改baseUrl为https://hongmao.run/cmd/。

3. 在菜单栏设置图标后，菜单首字符不能对齐

目前在文章的头部是这样设置菜单图标的：

1
2
3
4
5
6
7
8


+++
title = "Docker"
date = 2021-08-22T17:02:53+08:00
weight = 1
chapter = true
pre = "<i class='fab fa-docker'></i> "
description = "本章节主要讲述Docker的相关命令。"
+++

这样设置多篇文章后，由于图标不同，则菜单的字符不能对齐。但我发现本主题的官方文档中的“More”下的图标是对齐的，然后debug了一下，发现是由于缺少了一个样式导致的，即设置图标时，应该给其添加样式类fa-fw，如下所示：

1
2
3
4
5
6
7
8


+++
title = "Docker"
date = 2021-08-22T17:02:53+08:00
weight = 1
chapter = true
pre = "<i class='fab fa-fw fa-docker'></i> "
description = "本章节主要讲述Docker的相关命令。"
+++

这样设置后，问题解决。

【Hugo】hugo-theme-learn主题使用

文章目录

一、安装

二、基本使用

1. 创建一个章节

2. 创建一个内容文件

三、配置详解

四、特性的使用

1. 开启搜索

2. 更换Logo

3. 更换favicon

4. 创建一个首页

5. 使用短码设置提示块（notice）

6. 使用短码设置tab页

五、美化

1. 在菜单栏的标题前展示图标

六、常见问题解决

1. 点击logo或home时跳转到域名根目录的问题解决

2. 部署后搜索失效了

3. 在菜单栏设置图标后，菜单首字符不能对齐

文章目录

一、 安装

二、基本使用

1. 创建一个章节

2. 创建一个内容文件

三、配置详解

四、特性的使用

1. 开启搜索

2. 更换Logo

3. 更换favicon

4. 创建一个首页

5. 使用短码设置提示块（notice）

6. 使用短码设置tab页

五、美化

1. 在菜单栏的标题前展示图标

六、常见问题解决

1. 点击logo或home时跳转到域名根目录的问题解决

2. 部署后搜索失效了

3. 在菜单栏设置图标后，菜单首字符不能对齐

一、安装