Blog养成记(3) Hugo的语法高亮配置

前言

Hugo官网在这里给出了详细的语法高亮配置说明。

一般有以下几种常见方法：
1. 使用Hugo默认Chroma (弃，一些代码无法高亮)

使用Pygments (弃，一些代码无法高亮)
使用Highlight Shortcode (弃，高亮颜色渲染问题)
使用Highlight.js ✔️

使用Pygments进行高亮

Hugo从0.28版本开始默认使用Chroma来作语法高亮。Chroma使用go编写的，渲染速度很快。如果需要使用Pygments，需要先安装Pygments，并在网站配置文件中设置一些相关参数。

Pygments安装

我在建立Hugo镜像时已经安装了Pygments，不然需要先安装Pygments。如果在Debian和Ubuntu系统中可以用下面语句安装，其他系统也可参考：

$ sudo apt-get install python3-pygments

Pygments配置

下面是我按官网在 config.toml 中配置的参数：

[highlighting] 
  pygmentsUseClassic       = true
  pygmentsCodeFences       = true
  pygmentsStyle            = "autumn"

其中， pygmentsUseClassic=true 说明使用Pygments来进行语法高亮；
pygmentsCodeFences=true 使在code fence中的根据设置的语言标签进行语法高亮；
pygmentsStyle="autumn" 设置高亮的风格,可以在这里查看各高亮风格，选择最心仪的。

我选择了 autumn，下面是在code fence中的高亮示例：

#!/usr/bin/python3

from engine import RunForrestRun

"""Test code for syntax highlighting!"""

class Foo:
	def __init__(self, var):
		self.var = var
		self.run()

	def run(self):
		RunForrestRun()  # run along!

由于语法高亮渲染需要时间，因此语法高亮默认是放在缓存的，如果需要查看则需要清空缓存。

Pygments存在问题

与Chroma一样，Pygments对于一些格式无法进行高亮。现在发现的就有无法对shell脚本高亮，也无法识别toml文件。

使用Highlight Shortcode进行高亮

除了可以使用code fence高亮代码，还可Hugo内建的highlight shortcode进行高亮。highlight shortcode的优点是不仅可以根据语法进行高亮，还能在code fence中指定行进行mark，还可以设置代码的行号，比较灵活。

使用下面的语法：

{{< highlight python "linenos=inline, hl_lines=3 8 12, linenostart=199" >}}
# 代码放在这里
{{< /highlight >}}

其中，linenos=inline或者linenos=table提示显示代码前的行数，hl_lines设置高亮代码，linenostart设置代码行数的起始数字。

199#!/usr/bin/python3
200
201from engine import RunForrestRun
202
203"""Test code for syntax highlighting!"""
204
205class Foo:
206	def __init__(self, var):
207		self.var = var
208		self.run()
209
210	def run(self):
211		RunForrestRun()  # run along!

2018.8.13 `Highlight Shortcode`颜色渲染问题修正

如题，突然发现颜色渲染有问题，所以只能逐个看到底用了那个css。发现我的主页用了highlight shortcode的css样式和官网的不一样。鉴于不想花太多时间，只要能看就要，因此在override.css中加了强制的css样式，于是问题暂时打个不怎么好看的补丁，但至少highlight shortcode还是勉强可看了。

.highlight pre {
    background-color: #f7f7f7 !important;
    color: rgb(194, 192, 192) !important;
}

2018.8.21 自建shortcode替代Hightlight Shortcode

由于highlight shortcode的渲染样式实在是太诡异，难以调整，因此自己建立专门用于高亮的shortcode，这些shortcode也可以在代码块中使用，可以不仅只渲染一行，更为灵活方便。于是就可以弃用highlight shortcode了。具体内容详见Blog养成记15 创建shortcode模板便捷高亮内容。

使用highlight.js进行高亮

highlight.js这个插件使用起来特别方便，还可以定制化选择需要高亮的语言，只需要在highlight.js官网选择所需要的语言，下载即可。然后解压文件中，highlight.pack.js决定那些语言的代码会根据语法进行高亮，在style文件夹中选择喜欢的css样式文件，css文件决定代码高亮的颜色，最后我选择了github-gist.css

然后需要在<head>中增加：

<link rel="stylesheet" href="/path/to/styles/default.css">

在<body>结束前增加：

<script src="/path/to/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

Resource资源链接汇总

我建立的docker for Hugo开发镜像: Docker Hub上的repo、Github上的repo。
我的个人主页Hugo代码: blog-hugo

Hugo官网、关于语法高亮说明、pygments主题配色、highlight.js官网

版本控制

Version	Action	Time
1.0	Init	2018-01-09
1.1	增加tag、版本控制及资源链接	2018-01-17
1.2	highlight颜色修正	2018-08-13
2.0	修改结构，增加highlight.js	2018-08-21

ZHENG Zi'ou

前言