关于Hugo的Shortcodes系统的运用

Shortcodes 是Hugo创建的一种特殊的代码段，其诞生背景是在 Hugo 使用 Markdown 作为其简单的内容格式时，由于 Markdown 的特性，其在很多方面都无法很好地支持。 即使我们可以使用纯 HTML 来扩展可能性，但这恰好是一个坏主意。大家使用 Markdown, 正是因为它即使不经过渲染也可以轻松阅读，所以应该尽可能避免使用 HTML 以保持内容简洁。于是 Hugo 采用 Shortcodes 系统，其表现为一个简单的代码段，但是可以生成合理的 HTML 代码，非常符合 Markdown 的设计哲学。

既然 Hugo 为我们提供了这一方便的系统，我们就应当好好利用，此处我将按照可能使用的频率进行一些梳理与列举，便于以后查用。

Hugo 内置的Shortcodes

此处记录的为 Hugo 内置的一些 Shortcodes ，在使用时可以无视主题安装等限制进行使用。然而由于国内特殊的网络环境，有部分 Shortcodes 在使用后转换的效果无法正常呈现，故这里仅记录一个 figure ，其余可以参考这里。

figure

代码如

1

{< figure src="图片地址" title="图片标题" >}}

输出的 HTML 看起来如下:

1
2
3
4
5
6

<figure>
    <img src="图片地址"/>
    <figcaption>
        <h4>图片标题</h4>
    </figcaption>
</figure>

其还有诸多可选的位置参数, 由于 LoveIt 对此有所拓展，故不详细记录。

LoveIt 主题内置的Shortcodes

LoveIt 主题在 Hugo 内置的 shortcode 的基础上提供多个扩展的 shortcode。

1 style

本 shortcode 旨在使用简易的方式来为文中的某段内容进行样式设置，其含有两个参数：第一个参数是是自定义样式的内容，其支持 SASS的嵌套语法，并且以&指代这个父元素；第二个参数是包裹你要更改样式内容的 HTML 标签，默认值是div。

示例如下：

代码如下：

1
2
3

{< style "text-align:right; strong{color:#00b1ff;}" >}}
此为右对齐**段落**。
{< /style >}}

2 link

link这个 shortcode 是对 Markdown 中链接语法的替代物，其可以提供一些其他功能并且可以用于代码块中。其命名参数如下：

现将 LoveIt 对于此 shortcode 的举例复制如下:

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

{< link "https://assemble.io" >}}
或者
{< link href="https://assemble.io" >}}

{< link "mailto:contact@revolunet.com" >}}
或者
{< link href="mailto:contact@revolunet.com" >}}

{< link "https://assemble.io" Assemble >}}
或者
{< link href="https://assemble.io" content=Assemble >}}

{< link "https://github.com/upstage/" Upstage "Visit Upstage!" >}}
或者
{< link href="https://github.com/upstage/" content=Upstage title="Visit Upstage!" >}}

利用此语法输出效果如下:

3 image

其相当于对figure这个 shortcode 的替代, 其可选参数如下：

一个image示例如下:

1

{< image src="https://pub-99c785ad059849549a571cce9d506af0.r2.dev/PicGo/meme01.png" alt="一张表情包" caption="搜到的一个meme" >}}

输出效果如下:

4 admonition

用于插入提示用的横幅, 总共12种。全部呈现效果如下：

其有三个位置参数，分别为 type，title以及open。各参数的作用如其参数名，分别控制横幅的种类，横幅的标题以及是否展开。按照横幅从上至下的顺序，其type参数可选值有:note,abstract,info,tip,success,question,warning,failure,danger,bug,example,quote。

一个admonition示例如下:

其代码如下:

1
2
3

{< admonition tip "This is a tip" true >}}
一个 **技巧** 横幅
{< /admonition >}}

5 music

插入一个响应式音乐播放器, 其强大的功能甚至能进行歌单的播放。参数等较多, 可以参看官方文档进行配置。

一个music示例如下:

其代码如下:

1

{< music "https://music.163.com/playlist?id=2426208203" >}}

6 bilibili

提供了一个内嵌的用来播放 bilibili 视频的响应式播放器。需要的内容仅需其 BV 号以及其视频分P。

一个bilibili示例如下:(此为刘宝瑞先生单口相声集的第4P-黄半仙)

其代码为:

1
2
3

{< bilibili BV1ux411J7WW 4 >}}
或者
{< bilibili id=BV1ux411J7WW p=4 >}}

7 script

用于在文章中插入 JavaScript 脚本, 使用如下:

1
2
3

{< script >}}
代码内容
{< /script >}}

8 raw

用于插入原始 HTML 内容, 成对使用, 无参数。

其他 shortcodes

参见官方文档使用即可。