Shortcodes：Hugo 内置

XOlDKING 发布于 2023/10/07

总计 1485 字｜更新于 2023/10/25｜- 次阅读｜- 条评论

系列 - Shortcodes 语法

本文列出了 Hugo 提供的内置 Shortcodes 功能语法，可以在扩展 Markdown 渲染格式的同时保持内容简洁。

简介

Markdown 因其简洁的内容格式而备受亲赖，但就搭建网站页面内容而言，其支持的渲染格式多少有些捉襟见肘。因此，内容创作者们往往不得不在简洁的 Markdown 文档中插入原始 HTML 标签（例如视频 <iframe></iframe> 标签），这严重破坏了 Markdown 文档简洁、优雅的美感。

对此，Hugo 作为一个静态网站生成器，提出 Shortcodes 功能语法来规避上述 Markdown 语法的局限性。Shortcodes 是可以在 Markdown 内容文件中轻松使用的、简短的代码片段，Hugo 在构建网站页面时会按照预先定义好的 HTML 模版来渲染这些代码片段。

这种将文档内容与 HTML 渲染过程分离的设计思路很好的延续了 Markdown 的设计哲学。当我们更新 Shortcodes 中涉及或使用的 HTML 类、技术或标准后，Hugo 会在渲染过程中自动应用这些修改和更新。因此，使用 Shortcodes 除了可以维持 Markdown 文档的简洁外，还免除了因更新 HTML 框架而带来的繁杂的搜索和替换操作。

使用

Shortcodes 的使用格式一般为：
{{% shortcode-name parameter1="value1" parameter2="value2" ... %}}

Shortcodes 的界定符号有两种：
- {{% ... %}}：... 中的内容（如 Markdown 语法等）会被 Hugo 渲染为 HTML。
- {{< ... >}}：... 中的内容（一般为 HTML 代码）不会被 Hugo 再次渲染。
Shortcodes 的界定方式同 HTML 中的标签，也有两种：
- 单独：{{% shortcode-name parameters ... %}}
- 成对：{{% shortcode-name parameters %}} ... {{% /shortcode-name %}}
shortcode-name 为 Shortcades 的名称，必须位于开头。其后为 Shortcodes 传递的参数列表。
根据 Shortcodes 的具体定义，其参数有两种传递方式：
- 按参数名传递：parameter1="value1" parameter2="value2" ...
- 按位置顺序传递：value1 value2 ...

... 多行内容需使用原始字符串形式，如：

{{< myshortcode `This is some <b>HTML</b>,
and a new line with a "quoted sting".` >}}

参考

Hugo 内置 Shortcodes 的详细介绍以及示例请参考 Hugo 文档 - Shortcodes 。

figure

figure 拓展了 Markdown 中的 image 语法，支持 HTML5 <figure> 元素。

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


{{< figure 
    src         = "/images/WingsofLiberty.webp"
    link        = "https://www.newverse.wiki/"
    target      = "_blank"
    rel         = "nofollow noopener noreferrer"
    alt         = "alt of image"
    caption     = "**Caption** of image"
    title       = "Title of image"
    class       = "figure image"
    height      = "400"
    width       = "400"
    loading     = "lazy"
    attr        = "**Attr** of image"
    attrlink    = "https://www.newverse.wiki/"
>}}

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


<figure class="figure image">
    <a href="https://www.newverse.wiki/" target="_blank" rel="nofollow noopener noreferrer">
        <img src="/images/WingsofLiberty.webp" alt="alt of image" width="400" height="400" loading="lazy"/>
    </a>
    <figcaption>
        <h4>Title of image</h4>
        <p>
            <strong>Caption</strong> of image
            <a href="https://www.newverse.wiki/">
                <strong>Attr</strong> of image
            </a>
        </p>
    </figcaption>
<figure>

呈现的效果：

alt of image — Title of image
**Caption** of image **Attr** of image

gist

用于在网页中插入 GitHub gist 代码片段。

1

{{< gist spf13 7896402 >}}

1

<script type="application/javascript" src="https://gist.github.com/spf13/7896402.js"></script>

呈现的效果：

highlight

用于在网页中插入带语法高亮的代码片段。

参考

可选的高亮参数请参考 Hugo 文档 - Highlight 函数。

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


{{< highlight 
    html 
    "lineNos=table, hl_Lines=1 3-6, lineNoStar=42"
>}}
<section id="main">
    <div>
        <h1 id="title">{{ .Title }}</h1>
        {{ range .Pages }}
            {{ .Render "summary"}}
        {{ end }}
    </div>
</section>
{{< /highlight >}}

呈现的效果：

42
43
44
45
46
47
48
49


<section id="main">
    <div>
        <h1 id="title">{{ .Title }}</h1>
        {{ range .Pages }}
            {{ .Render "summary"}}
        {{ end }}
    </div>
</section>

param

获取当前页面中前置参数（front matter）的值，若当前页面中未设置该前置参数则获取网站配置 hugo.toml 中相应参数的值，若网站配置文件中也未找到相应参数，则返回 ERROR。

如获取当前页面的标题：

1

{{% param title %}}

呈现的效果：

Shortcodes：Hugo 内置

ref 与 relref

在制作站内超链接时，按照给定的其相对路径（例如 blog/post.md）或逻辑名称（post.md），查找并返回所找到页面的链接（ref）或相对链接（relref）。

1
2


[Markdown 基本语法]({{< ref "/senses/MarkdownBasics.md" >}})  
[Markdown 扩展语法]({{< relref "MarkdownExtended.md#emoji" >}})

1
2


<a href="http://www.newverse.wiki/senses/markdownbasics/">Markdown 基本语法</a>
<a href="/senses/markdownextended/#emoji">Markdown 扩展语法</a>

呈现的效果：

Markdown 基本语法
 Markdown 扩展语法

用于在网页中插入 Twitter 展示页面。

1

{{< tweet user="SanDiegoZoo" id="1453110110599868418" >}}

1
2
3
4
5
6
7
8
9


<blockquote class="twitter-tweet" data-dnt="true">
    <p lang="en" dir="ltr">
        Owl bet you&#39;ll lose this staring contest 🦉 
        <a href="https://t.co/eJh4f2zncC">pic.twitter.com/eJh4f2zncC</a>
    </p>
    &mdash; San Diego Zoo Wildlife Alliance (@sandiegozoo) 
    <a href="https://twitter.com/sandiegozoo/status/1453110110599868418?ref_src=twsrc%5Etfw">October 26, 2021</a>
</blockquote>
<script async src="https://platform.twitter.com/widgets.js" charset="utf-8"></script>

呈现的效果：

Bug

无法加载 twitter 展示页面

vimeo

用于在网页中插入 vimeo 视频。

1
2
3


{{< vimeo 55073825 >}}
或者
{{< vimeo id="55073825" class="my-vimeo-wrapper-class" title="My vimeo video" >}}

1
2
3


<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
    <iframe src="https://player.vimeo.com/video/55073825" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" title="vimeo video" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
</div>

呈现的效果：

youtube

用于在网页中插入 YouTube 视频。

1
2
3


{{< youtube w7Ft2ymGmfc >}}
或者
{{< youtube id="w7Ft2ymGmfc" autoplay="false" title="A New Hugo Site in Under Two Minutes" >}}

1
2
3


<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
    <iframe src="https://www.youtube.com/embed/w7Ft2ymGmfc" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" allowfullscreen title="A New Hugo Site in Under Two Minutes"></iframe>
</div>

呈现的效果：

【参考】

Hugo 文档 - Shortcodes