配置文件详解

此处配置项并非最全、也不保证最新，只是我个人在使用这些配置时的记录。

 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
42
43
44
45
46
47
48
49
50

# 网站的语言代码。它在默认RSS模板中使用，对于多语言站点非常有用，默认值为空字符串
languageCode = "zh-cn"
# 没有语言指示器的内容将默认为是该语言，默认值为“en”，如果此属性值与languageCode的值不同，则可能触发浏览器提示进行网页翻译
defaultContentLanguage = "en" 

# 开启对emoji的支持，默认是关闭的
enableEmoji = true

# 配置标记
[markup]
  # 目录相关
  [markup.tableOfContents]
    # 纳入目录的最小标题级别，默认为3
    endLevel = 3
    # 是否排序，其实就是是否在目录的前面添加序号“1. ”、"2. "等等
    ordered = false
    # 纳入目录的最大标题级别，默认为2
    startLevel = 2
  # 代码高亮相关
  [markup.highlight]
    # 是否为代码行标开启锚链接，开启后，每一行代码都有锚链接，但是可能会重复
    # 例如第12行代码的链接：http://localhost:1313/test/#12
    anchorLineNos = false
    # 其实就是是否开启按不同语言显示不同的高亮效果，置为false后，代码全是灰的，没有高亮效果
    codeFences = true
    # 当Markdown文件中对代码块未指定语言时，是否自动推测语言
    guessSyntax = false
    # 高亮的行，一般不会做全局设置，如果想设置某一行或某几行高亮的话，可以在代码块单独设置
    hl_Lines = ""
    # 在生成行号的锚链接时添加前缀，例如如果设置该属性为”xxx“的话
    # 则第12行代码的链接可能是：http://localhost:1313/test/#xxx-12
    lineAnchors = ""
    # 开始的行号，一般是从1开始，此设置也可以在代码块单独设置
    lineNoStart = 1
    # 是否展示行号
    lineNos = false
    # 是否将行号置为独立的table内，而不是和代码行在一起，和代码行在一起时，复制多行代码时行号也会被复制
    lineNumbersInTable = true
    noClasses = true
    # 指定代码高亮的风格
    style = "monokai"
    # tab键的宽度
    tabWidth = 4
  # goldmark相关
  [markup.goldmark]
    # 渲染器相关配置
    [markup.goldmark.renderer]
      # 默认情况下，Goldmark不会呈现原始HTML和潜在危险的链接。如果你有很多内联HTML或JavaScript，你可能需要打开它。
      # 不打开意味着Markdown中嵌入的HTML代码不会生效
      unsafe = false

常见问题

1. 如何在段落中设置锚点

我是在使用“hugo-book”主题时遇到了这样一个需求，需要在页面点击某个链接后，自动链接到该页的某个地方，而且这个地方还不是标题，只是普通段落。如果是标题的话，默认会为其生成一个锚点链接，而普通段落则不会。

寻找了一下解决方案，发现可以通过嵌入HTML代码来实现，例如：

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

```markdown
[点击](#5)可跳转至5

1

2

3

4

<span id="5">5</span>
```

效果如下：

点击可跳转至5

1

2

3

4

5

但是，当启动后却没有效果，看了下“5”的网页代码，发现并没有我们设定的<span>标签包裹着它，所以它才没有效果。于是查了下资料，Hugo采用的是Goldmark来解析Markdown语法，要想在Markdown中嵌入HTML代码，需要在配置文件中开启它：

1
2
3
4

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

2. 如何自定义简码（shortcode）

简码，是Hugo所支持的一种嵌入HTML的方式。它简化了在Markdown文件中嵌入HTML代码的操作。

所谓简码，其实就是如下所示的标签：

1

{{< img src="https://xxxx.jpg" >}}

固定格式就是{{< 简码标识 >}}包裹，上面示例中的img便是简码标识，通过该标识，Hugo可以找到对应的模板以用来解析该简码，src是参数。

上面的简码在被解析后可能就如下所示：

1

<img src="https://xxxx.jpg" alt="">

所以简码的工作就是通过简单的参数，让Hugo为我们生成对应的HTML代码。

每一个简码都有对应的模板，其放在项目根目录的layouts/shortcodes/路径下，如果找不到，会去当前启用的主题的该路径下寻找对应模板，如果还找不到，且Hugo本身并未提供该简码，则会报错。

所以，如果我们想重新设定简码模板或者定义一个新的简码模板，可以在项目根目录的layouts/shortcodes/路径下创建对应的模板。

我们此处创建一个新的简码模板，将其放在项目根目录的layouts/shortcodes/路径下，命名为“pic.html”。这个命名很重要，我们如此命名，也就意味着在Markdown中必须这样使用它{{< pic >}}。

下面开始编写该简码模板，先明确我们的需求：用户可使用该简码在文章中插入图片，且可指定图片的水平对齐方式，当不指定对齐方式时，默认居中对齐，除此之外还可以指定图片宽度。

首先简码模板中有两种获取参数的方法：

  1. 命名参数

    1
2

    /* 获取参数名为src的参数值 */
.Get "src"

    假设在Markdown中是这样使用该简码的：{{< pic src="https://xxx.jpg" >}}，那我们上述示例中获取到的值即为“https://xxx.jpg”。

  2. 位置参数

    1
2

    /* 获取第一个参数 */
{{ .Get 0 }}

    假设在Markdown中是这样使用该简码的：{{< pic "https://xxx.jpg" center >}}，那我们上述示例中获取到的值即为“https://xxx.jpg”。如果我们使用{{ .Get 1 }}，那获取到的就是“center”，因为索引位置是从0开始的。

简码模板中可用的语法有很多，此处无法一一列出，可参考Hugo官方文档。

最终，我们编写的模板代码如下：

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

<!-- 判断是否存在命名参数 -->
{{ if .IsNamedParams }}
<!-- 获取对齐方式，with .Get "align"代表：是否设定的了属性align的值 -->
<div style='text-align: {{ with .Get "align" }}{{ . }}{{ else }}{{ "center" }}{{ end }}'>
    <!-- 存在命名参数，获取参数src的值，注意此处的src必须用双引号包裹，否则解析时会报错 -->
    <img src='{{ .Get "src" }}' width='{{ with .Get "width" }}{{ . }}{{ else }}{{ "auto" }}{{ end }}' alt=''>
</div>
{{ else }}
<!-- 获取对齐方式 -->
<div style='text-align: {{ with .Get 1 }}{{ . }}{{ else }}{{ "center" }}{{ end }}'>
    <!-- 不存在命名参数，获取第一个参数（即对应索引位置为0的参数） -->
    <img src='{{ .Get 0 }}' width='{{ with .Get 1 }}{{ . }}{{ else }}{{ "auto" }}{{ end }}' alt=''>
</div>
{{ end }}

我们可以按照如下方式使用该简码：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

居右展示图片
{{< pic src="https://img.hongmao.run/blog/2021/07/AbstractCollection.png" align="right" width="20%" >}}

居中展示图片
{{< pic src="https://img.hongmao.run/blog/2021/07/AbstractCollection.png" >}}

居右展示图片
{{< pic "https://img.hongmao.run/blog/2021/07/AbstractCollection.png" "20%" right >}}

居中展示图片
{{< pic "https://img.hongmao.run/blog/2021/07/AbstractCollection.png" >}}