MatNoble
MatNoble

Hugo Shortcodes 实战教程：从自定义 HTML 到集成 B 站与 Apple Music

动手玩创意
动手玩创意

操练起来!

前言

Shortcodes 翻译为: 短代码或者简码

简码是内容文件中的一个简单片段，Hugo将使用预定义的模板对其进行呈现.

除了更清洁的Markdown外，短代码还可以随时更新以反映新的类，技术或标准. 在网站生成时，Hugo简码将轻松合并到您的更改中. 您避免了可能复杂的搜索和替换操作.

需注意

本博客基于 HUGO, 使用的是 reuixiy 开发的 MemE 主题, 但由于该主题暂时不支持 Shortcodes (与LaTeX\LaTeX 渲染冲突), 所以, 如果你用的也是该主题, 又想玩玩儿 Shortcodes, 那么你需要作出一些小修改, 修改办法见下方链接.

MemE v4.0.0 breaks Hugo shortcodes

  • 为防止 shortcodes 语法被博客渲染，应在代码示例中使用 {{< myshortcode >}} 这样的格式进行展示。

输出结果为:

{{< myshortcode >}}

Shortcodes 实例

当前年 Year

官网例子, 输出今年的年份.

1

今年是 {{< year >}} 年.

今年是 2026 年.

只需建立 ./layouts/shortcodes/year.html

1

{{ now.Format "2006" }}

mark 标记支持 

1

{{< mark text="HTML 标记" >}}
HTML 标记
实现方法很简单, 只需创建 `mark.html`
1
2
3
4
5

<!-- ./layouts/shortcodes/mark.html 
https://blog.matnoble.top/posts/shortcodes-practice-tutorial-for-hugo/#mark-标记支持
-->

<mark>{{ .Get "text" }}</mark>

abbr 缩写支持 

1

{{< abbr title="Huazhong University of Science and Technology" text="HUST" >}}
HUST
实现方法也很简单, 只需创建 `abbr.html`
1
2
3
4
5

<!-- ./layouts/shortcodes/abbr.html 
https://blog.matnoble.top/posts/shortcodes-practice-tutorial-for-hugo/#abbr-缩写支持
-->

<abbr title="{{ .Get "title" }}">{{ .Get "text" }}</abbr>

维基百科 Wikipedia

借鉴自GitHub, 举个栗子:

1

{{< wp tag="Wikipedia:历史上的今天" lang="zh" title="历史上的今天" >}}
历史上的今天

blockquote

借鉴自GitHub, 举个栗子:

1
2
3
4
5
6

{{< blockquote author="李健" link="https://baike.baidu.com/item/%E6%87%82%E5%BE%97/22699721" title="《懂得》" >}}
花开花谢 白天黑夜<br />
一切自然 又不尽然<br />
春夏秋冬 经过才懂<br />
世间冷暖 无非自然
{{< /blockquote >}}

花开花谢 白天黑夜
一切自然 又不尽然
春夏秋冬 经过才懂
世间冷暖 无非自然

image with caption 

1

{{< imgcap src="https://cdn.jsdelivr.net/gh/MatNoble/Images/win/lebron-202307182307397.png" title="无比想念最好的骑士" >}}
无比想念最好的骑士
无比想念最好的骑士

实现稍复杂一些, 依旧建立 `imgcap.html`
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

<!--
./layouts/shortcodes/imgcap.html
https://blog.matnoble.top/posts/shortcodes-practice-tutorial-for-hugo/#image-with-caption
-->

<span class="caption-wrapper">
  <img class="caption" src="{{ .Get "src" }}"
       title="{{ .Get "title" }}"
       alt="{{ if .Get "alt" }}{{ .Get "alt" }}{{ else }}{{ .Get "title" }}{{ end }}"
       width="{{ if .Get "width" }}{{ .Get "width" }}{{ else }}95%{{ end }}"
       >
  <span class="caption">◎ {{ .Get "title" }}</span>
</span>

其中, src 和 title 为必填项, alt 和 width 为选填项, alt 默认与 title 保持一致, width 默认值为: 95% .

Hugo-notice

This is not a standalone theme. It is a Hugo theme component providing a shortcode: notice to display nice notices. Four notice types are provided: warning, info, note and tip.

hugo-notice 是一个制作十分精美的短代码, 非常感谢原作者的付出, 但使用并不需要把他的仓库 copy 到本地, 只需将 notice.html copy 到 ./layouts/shortcodes/ 下, 如需要翻译, 且使用 MemE 主题, 只需要在根目录下创建 ./i18n/zh-cn.toml

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

[warning]
other = "警告"

[note]
other = "注释"

[info]
other = "引言"

[tip]
other = "小贴示"

显示效果如下:

Warning 

1
2
3

{{< notice warning >}}
这是告诫! 请注意!
{{< /notice >}}

这是告诫! 请注意!

Info 

1
2
3

{{< notice info >}}
这是引言
{{< /notice >}}

这是引言

Tip 

1
2
3

{{< notice tip >}}
这是小贴示
{{< /notice >}}

这是小贴示

Note 

1
2
3

{{< notice note >}}
这是注释
{{< /notice >}}

这是注释

音乐 Music

基于 MetingJS 制作 ./layouts/shortcodes/music.html

{{< music id="569200212" type="song" server="netease" >}}
optiondefaultdescription
idrequiresong id / playlist id / album id / search keyword
serverrequiremusic platform: netease, tencent, kugou, xiami, baidu
typerequiresong, playlist, album, search, artist

更多选项看这里

显示效果:

该 shortcodes 存在问题! 会导致 TOC 目录点击失效, 所以, 暂时只能将音乐放到没有目录的页面 👇

爱音乐
爱音乐

视频 Video

YouTube

原生支持 YouTube, 代码如下

1

{{< youtube ID >}}

B 站

创建 ./layouts/shortcodes/bili.html 使其支持 B 站

1

{{< ili aid="AID" cid="CID" >}}

优酷 YOUKU

创建 ./layouts/shortcodes/youku.html 使其支持 YOUKU

1

{{< youku id="ID" >}}

GitHub gist

原生支持, 添加 GitHub gist

1

{{< gist MatNoble b8d6a9541221fef7c30bf214d3505836 >}}

很多博客都支持添加 友链, 本博客也不例外, 在这里 借鉴自 hugo-friendlinks, 针对本主题, 稍加修改.

1

{{< friend name="数学小兵儿" url="https://blog.matnoble.top/" logo="/icons/android-chrome-512x512.png" word="数学＆计算机 我都爱" >}}

blog logo
数学小兵儿
数学＆计算机 我都爱

提供下载 download

以上所有 shortcodes 代码都可以访问以下 GitHub 链接下载, 欢迎发现问题的同学提交Issues!

These are shortcodes that I have created for the Hugo static blogging engine.

更多示例

  1. shortcodes directory for spf13.com
  2. shortcodes directory for the Hugo docs