内容管理

短代码

什么是短代码

Hugo喜欢Markdown，因为它的内容格式简单明了，但是有些时候Markdown也会有不足之处。通常，在Markdown内容中，内容作者被迫添加原始的HTML代码（例如，视频的<iframe>）。我们认为这与Markdown语法的简洁之美相矛盾。

Hugo创建了短代码来解决这些限制。

短代码是一个简单的片段，位于内容文件中，Hugo将使用预定义的模板来渲染它。请注意，短代码在模板文件中不起作用。如果你需要在模板中提供类似短代码的功能，你很可能需要[局部模板][partials]。

除了更干净的Markdown之外，短代码也可以随时更新以反映新的类、技术或标准。在网站生成时，Hugo的短代码将轻松合并您的更改。这样，您就避免了繁琐的搜索和替换操作。

使用短代码

在你的内容文件中，可以通过调用 {{% shortcodename 参数 %}} 来调用短代码。短代码参数以空格分隔，具有内部空格的参数可以用引号引起来。

在短代码声明中，第一个词总是短代码的名称。参数位于名称之后。根据短代码的定义方式，参数可以是命名的、定位的，也可以同时存在，但是不能在一个调用中混合使用不同类型的参数。命名参数的格式与HTML的格式相同，采用 name="value" 的格式。

某些短代码使用或需要闭合短代码。与HTML类似，开放和闭合的短代码匹配（仅限名称），闭合声明前面加上一个斜杠。

这里有两个配对的短代码示例：

{{% mdshortcode %}}在*中间*处`处理`的内容。{{% /mdshortcode %}}

{{< highlight go >}} 这里有一堆代码 {{< /highlight >}}

上面的示例使用了两种不同的界定符，第一个示例中使用了%字符，第二个示例中使用了<>字符。

使用原始字符串参数的短代码

你可以使用原始字符串字面量将多行作为参数传递给短代码：

{{<  myshortcode `这是一些 <b>HTML</b>，
以及一个带有"引用字符串"的新行。` >}}

使用Markdown的短代码

以%作为最外层分隔符的短代码将在发送到内容渲染器时完全渲染。这意味着短代码的渲染输出可以成为页面的目录、脚注等的一部分。

不使用Markdown的短代码

<字符表示短代码的内部内容不需要进一步渲染。通常，不使用Markdown的短代码包括内部HTML：

{{< myshortcode >}}<p>你好 <strong>世界！</strong></p>{{< /myshortcode >}}

嵌套短代码

你可以在其他短代码中调用短代码，方法是创建自己的模板，利用.Parent变量。.Parent允许你检查调用短代码的上下文。参见[短代码模板][sctemps]。

使用Hugo内置的短代码

Hugo附带了一组预定义的短代码，代表常见用法。这些短代码提供给作者使用，以保持你的Markdown内容的清洁。

figure

figure是Markdown中图像语法的扩展，它没有提供更语义化的[HTML5 <figure> 元素][figureelement]的缩写。

figure短代码可以使用以下命名参数：

src
要显示图像的URL。
link
如果图像需要添加超链接，则为目标的URL。
target
如果设置了link参数，则为可选的target属性的URL。
rel
如果设置了link参数，则为可选的rel属性的URL。
alt
在图像无法显示时的替代文本。
title
图像标题。
caption
图像标题。caption值中的Markdown将被渲染。
class
HTML figure标签的class属性。
height
图像的height属性。
width
图像的width属性。
loading
图像的loading属性。
attr
图像属性文本。attr值中的Markdown将被渲染。
attrlink
如果属性文本需要超链接，请添加目标的URL。

figure输入示例

figure-input-example.md
{{< figure src="elephant.jpg" title="日落时的大象" >}}

figure输出示例 

<figure>
  <img src="elephant.jpg">
  <figcaption>日落时的大象</figcaption>
</figure>

gist

要显示一个GitHubgist，使用以下URL：

https://gist.github.com/user/50a7482715eac222e230d1e64dd9a89b

将以下内容包含在你的markdown中：

{{< gist user 50a7482715eac222e230d1e64dd9a89b >}}

这将按文件名字母顺序显示gist中的所有文件。

要显示gist中的特定文件：

{{< gist user 50a7482715eac222e230d1e64dd9a89b 1-template.html >}}

呈现：

highlight

要显示一个带有突出显示的代码示例：

{{< highlight go-html-template >}}
{{ range .Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
{{< /highlight >}}

呈现：

{{ range .Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}

要指定一个或多个突出显示选项，请包含引号括起来的以逗号分隔的列表：

{{< highlight go-html-template "lineNos=inline, lineNoStart=42" >}}
{{ range .Pages }}
  <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
{{ end }}
{{< /highlight >}}

呈现：

42{{ range .Pages }}
43  <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a></h2>
44{{ end }}

instagram

instagram短代码使用Facebook的oEmbed Read功能。Facebook的开发者文档表示：

  • 此权限或功能需要成功完成App Review流程，该应用程序才能访问实时数据。了解更多
  • 该权限或功能仅在进行业务验证时可用。在应用程序访问数据之前，您还可能需要签署其他合同。在这里了解更多详情

你必须获取访问令牌才能使用instagram短代码。

如果你的站点配置是私有的：

hugo.
      
services:
  instagram:
    accessToken: xxx

[services]
  [services.instagram]
    accessToken = 'xxx'

{
   "services": {
      "instagram": {
         "accessToken": "xxx"
      }
   }
}

如果你的站点配置是_公开的_，请使用环境变量设置访问令牌：

HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify

要显示一个Instagram帖子，使用以下URL：

https://www.instagram.com/p/BWNjjyYFxVx/

在你的markdown中，包含以下内容：

{{< instagram BWNjjyYFxVx >}}

param

从当前页面的参数集合中获取一个值，如果在前置元数据或站点参数值中找不到具有给定键的参数，则记录一个ERROR。

{{< param testparam >}}

由于testparam是在本页的前置元数据中定义的参数，其值为Hugo牛！，上面的示例将打印：

Hugo牛！

要访问深层嵌套的参数，请使用“点语法”，例如：

{{< param "my.nested.param" >}}

ref 和 relref

这些短代码将通过相对路径（例如，blog/post.md）或逻辑名称（post.md）查找页面，并返回找到页面的永久链接（ref）或相对链接（relref）。

ref和relref还使您能够创建适用于Hugo生成的页眉链接的片段链接。

ref 和 relref 需要一个必需的引用参数，带引号并处于位置 0。

ref 和 relref 输入示例 

[好东西]({{< ref "blog/neat.md" >}})
[Who]({{< relref "about.md#who" >}})

ref 和 relref 输出示例

假设启用了标准的Hugo美化URL。

<a href="https://example.org/blog/neat">好东西</a>
<a href="/about/#who">Who</a>

tweet

要显示一个Twitter帖子，使用以下URL：

https://twitter.com/SanDiegoZoo/status/1453110110599868418

在你的markdown中，包含以下内容：

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

呈现：

vimeo

要显示一个Vimeo视频，使用以下URL：

https://vimeo.com/channels/staffpicks/55073825

在你的markdown中，包含以下内容：

{{< vimeo 55073825 >}}

呈现：

youtube

youtube短代码嵌入一个响应式视频播放器，用于YouTube视频。只需要视频的ID，例如：

https://www.youtube.com/watch?v=w7Ft2ymGmfc

youtube示例输入

复制在视频URL的v=后面的YouTube视频ID，并将其传递给youtube短代码：

example-youtube-input.md
{{< youtube w7Ft2ymGmfc >}}

此外，你可以通过将autoplay参数设置为true来自动开始播放嵌入的视频。请记住，您不能混合使用命名参数和未命名参数，所以您需要将尚未命名的视频ID分配给参数id：

example-youtube-input-with-autoplay.md
{{< youtube id="w7Ft2ymGmfc" autoplay="true" >}}

出于无障碍原因，最好为您的YouTube视频提供一个标题。您可以通过在短代码中提供 title 参数来实现。如果不提供标题，则将使用默认值“YouTube Video”。

example-youtube-input-with-title.md
{{< youtube id="w7Ft2ymGmfc" title="两分钟内创建一个新Hugo站点" >}}

youtube示例输出

使用前面的youtube示例，将以下HTML添加到你呈现的站点的标记中：

example-youtube-output.html
<div style="position: relative; padding-bottom: 56.25%; height: 0; overflow: hidden;">
  <iframe src="https://www.youtube.com/embed/w7Ft2ymGmfc?autoplay=1" style="position: absolute; top: 0; left: 0; width: 100%; height: 100%; border:0;" allowfullscreen title="YouTube Video"></iframe>
</div>

youtube显示示例

使用前面的youtube示例（不含autoplay="true"），下面模拟了访问者在你的网站上的显示体验。当然，最终的显示将依赖于你的样式表和周围的标记。视频还包含在[Hugo文档的快速入门][quickstart]中。

隐私配置

要了解如何配置你的Hugo站点以符合新的欧盟隐私法规，请参见Hugo和GDPR。

创建自定义短代码

要了解更多关于创建自定义短代码的信息，请参见短代码模板文档。

See also

Last updated: November 23, 2023: first release (332dc4cd7)
Improve this page