短代码是什么？

Hugo的设计者们中意Markdown，内容格式简单，但是有时Markdown会有不足。 内容作者经常会被逼着添加在Markdown内容中添加原生HTML(比如，video，<iframe>等)。 我们认为这与Markdown格式的漂亮简单冲突。

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

短代码是内容文件中的简单的代码段，hugo会使用预定义的模板来呈现它。 注意短代码在模板文件中不会工作。 如果您在模板中需要短代码提供的插入代码之类的功能， 很多时候您想要的是部分模板。

在美化Markdown之外，短代码可以在任何时间更新以反应新的类、技巧或标准。在站点生成的时间点，Hugo短代码会简单合并您的变化，避免了可能的复杂查询替换操作。

使用短代码

在内容文件中，调用短代码的形式是{{% shortcodename parameters %}}. 短代码参数是空格分隔的，内部有空格的参数需要使用引号括起来.

短代码声明中第一个词总是短代码的名称。参数跟随名称。依赖于短代码的定义方式，参数可以是有名参数、位置参数、或者都是，虽然在单独一次调用中不能混合参数类型。有名参数的格式以HTML的格式 name="value"为模型.

有些短代码使用或者要求结束的短代码。又和HTML一样，开始和结束的短代码要匹配(仅仅名称)，结束的短代码声明前面附加了斜线

下面是配对短代码的两个例子:

1

{{% mdshortcode %}}Stuff to `process` in the *center*.{{% /mdshortcode %}}

1

{{< highlight go >}} A bunch of code here {{< /highlight >}}

上面例子使用了两个不同的分隔符号，区别在于第一个使用了%字符作为分隔符号而第二个使用了 <> 字符。

使用原生字符串参数

可以给短代码传递多行字符串作为参数，多行字符串需要使用原生字符串:

1
2

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

短代码内包含Markdown 标记

从Hugo 0.55 版本开始我们改变了%分隔符的工作方式。 使用%作为最外层分隔符的短代码将会在传递给内容呈现器时完全呈现出来，意味着它们能够成为生成的目录表或者脚注等的一部分。

如果需要旧版本的工作方式，请在短代码模板的开始部分添加下面的代码:

1

{{ $_hugo_config := `{ "version": 1 }` }}

短代码内不包含Markdown

鼓号<标明短代码的内部内容不需要进一步呈现。没有Markdown的短代码经常会包含内部HTML代码。

1

{{< myshortcode >}}<p>Hello <strong>World!</strong></p>{{< /myshortcode >}}

嵌套的短代码

您可以在短代码里面调用其他短代码，需要创建内部短代码的模板，内部短代码可以使用.Parent 变量. .Parent 允许您检查短代码被调用的上下文。参考 短代码模板.

使用Hugo内置的短代码

Hugo 附带了一系列的预定义的代表非常普遍用法的短代码。提供这些短代码给内容作者带来便利，同时保持markdown内容整洁。

图像 figure

figure 是markdown中图像格式的扩展，markdown中图像不支持更语意化的HTML5 <figure> element.

figure短代码可以使用下面的具名参数:

src
于展示的图像的URL
link
如果需要对图像添加链接，目标URL.
target
如果link参数已经设置，URL可选的 target 属性
rel
如果link参数已经设置, 对于URL的可选属性
alt
如果image无法显示，替换显示的文本.
title
图片标题.
caption
图片说明. 在caption值内的markdown会被呈现输出
class
HTML 标签 figure 的class属性.
height
图片高度 height attribute of the image.
width
图片宽度 width attribute of the image.
attr
图片归因文字。attr值内的markdown标记会被呈现输出
attrlink
如果attr属性需要添加链接，这是目的URL.

figure 例子输入

1

{{< figure src="/media/spf13.jpg" title="Steve Francia" >}}

figure 输出

1
2
3
4
5
6

<figure>
  <img src="/media/spf13.jpg"  />
  <figcaption>
      <h4>Steve Francia</h4>
  </figcaption>
</figure>

gist GitHub代码片段

博客在写文章时经常会包含Github代码片段。假设我们想使用这个这个URL所在的gist

1

https://gist.github.com/spf13/7896402

我们可以使用URL中获取的用户名和gist id，嵌入代码片段在我们的内容中:

1

{{< gist spf13 7896402 >}}

例子 gist 输入

如果gist包含几个文件，您想引用其中一个，您可以传递文件名称(带引号的)作为可选的第三个参数:

1

{{< gist spf13 7896402 "img.html" >}}

例子 gist 输出