7 分钟阅读
https://gohugo.io/content-management/shortcodes/
简码是在您的内容文件中调用内置或自定义模板的简单代码片段。
Hugo喜欢Markdown,因为它的简单内容格式,但有时Markdown存在局限性。通常,内容作者被迫将原始HTML(例如视频<iframe>
)添加到Markdown内容中。我们认为这与Markdown语法的美丽简洁相矛盾。
Hugo创建了简码来规避这些限制。
简码是内容文件中的简单代码片段,Hugo将使用预定义的模板进行渲染。请注意,简码在模板文件中不起作用。如果您需要简码提供的此类插入(drop-in)功能,但在模板中,则很可能需要局部模板。
除了更干净的Markdown外,简码可以随时更新以反映新的类、技术或标准。在站点生成的时候,Hugo简码将轻松合并您的更改。您避免了可能复杂的搜索和替换操作。
在您的内容文件中,可以通过调用\{\{\% shortcodename parameters \%\}\}
来调用简码。简码参数由空格分隔,具有内部空格的参数可以用引号引起来。
简码声明中的第一个单词始终是简码的名称。参数跟在名称后面。根据简码的定义方式,参数可以是命名的、位置的或两者兼有,但不能在单个调用中混合使用参数类型。命名参数的格式与HTML的格式name="value"
相似。
一些简码使用或需要闭合简码。与HTML一样,开放和关闭简码匹配(仅名称),关闭声明前缀有一个斜杠。
以下是成对的简码的两个示例:
|
|
上面的例子使用两个不同的定界符,不同之处在于第一个中有%
字符,第二个中有<>
字符。
您可以使用原始字符串字面值将占据多行的参数传递给简码:
|
|
在Hugo 0.55中,我们改变了%
定界符的工作方式。使用 %
作为最外层定界符的简码现在将在发送到内容渲染器时完全渲染。它们可以成为生成的目录(table of contents)、脚注(footnotes)等的一部分。
如果您想要旧的行为,可以在简码模板的开头放置以下行:
|
|
<
字符表示简码的内部内容不需要进一步渲染。通常,不带Markdown的简码包括内部HTML:
|
|
您可以通过创建自己的模板来利用.Parent变量
在其他简码中调用简码。 .Parent
允许您检查简码被调用的上下文。请参见简码模板。
Hugo附带了一组预定义的简码,代表非常常见的用法。这些简码提供给作者方便,并使您的Markdown内容保持干净。
figure
figure
是 Markdown 中图像语法的扩展,它不提供更语义化的 HTML5的简写形式。
figure
简码可以使用以下命名参数:
src
要显示的图像的URL。
link
如果图像需要超链接,目标的URL。
target
如果设置了link
参数,则为URL的可选target
属性。
rel
如果设置了link
参数,则为URL的可选rel
属性。
alt
如果无法显示图像,则为图像的替代文本。
title
图像标题。
caption
图像标题。在caption
的值中的Markdown将被渲染。
class
HTML figure
标记的class
属性。
height
图像的height
属性。
width
图像的width
属性。
attr
图像归属文本。在attr
的值中的Markdown将被渲染。
attrlink
如果需要将归属文本超链接,则为目标的URL。
figure
输入figure-input-example.md
|
|
figure
输出
|
|
gist
要显示此URL的GitHub代码片段(gist):
|
|
在您的Markdown中包含以下内容:
|
|
这将按文件名按字母顺序显示gist中的所有文件。
|
|
要显示gist中的特定文件:
|
|
渲染结果:
|
|
highlight
用于展示高亮代码示例:
|
|
渲染结果:
|
|
若要指定一个或多个高亮选项,请使用引号包围、逗号分隔的列表:
|
|
渲染结果:
|
|
instagram
instagram
简码使用Facebook的oEmbed Read功能。Facebook开发者文档说明:
您必须获得Access Token才能使用instagram
简码。
如果您的站点配置是私有的:
config.
=== “yaml”
``` yaml
services:
instagram:
accessToken: xxx
```
=== “toml”
``` toml
[services]
[services.instagram]
accessToken = 'xxx'
```
=== “json”
``` json
{
"services": {
"instagram": {
"accessToken": "xxx"
}
}
}
```
如果您的站点配置不是私有的,请使用环境变量设置 Access Token:
|
|
如果您正在使用Client Access Token,您必须使用管道符(
APPID|ACCESSTOKEN
)将Access Token与您的App ID 结合起来。
要显示具有此 URL 的 Instagram 帖子:
|
|
在您的 Markdown 中包含以下内容:
|
|
param
从当前页面的前置元数据中的 params 集合获取一个值,并回退到站点参数值。如果在其中都找不到具有给定键的参数,则会记录一个 ERROR
。
|
|
由于 testparam
是此页面前置元数据中定义的参数,其值为 Hugo Rocks!
,因此以上内容将打印出:
Hugo Rocks!
要访问深层嵌套的参数,请使用"点语法",例如:
|
|
ref
和relref
这些简码将通过相对路径(例如blog/post.md
)或逻辑名称(post.md
)查找页面,并返回找到的页面的永久链接(ref
即 permalink )或相对永久链接(relref
即 relative permalink)。
ref
和relref
还使得可以为Hugo生成的标题链接创建片段链接(fragmentary link)。
在交叉引用文档中阅读有关
ref
和relref
的更详细描述。
ref
和 relref
接受恰好一个必需的引用参数,引用参数必须在位置 0
上引用并使用引号引起来。
ref
和relref
输入
|
|
ref
和relref
输出 假设标准的 Hugo 美化 URL 已经开启。
|
|
tweet
要显示此URL的Twitter帖子:
|
|
请在您的Markdown 中包含以下内容:
|
|
渲染结果:
vimeo
要显示此 URL 的 Vimeo 视频:
|
|
请在您的Markdown 中包含以下内容:
|
|
渲染结果:
如果您想进一步自定义 YouTube 或 Vimeo 输出的视觉样式,请在调用简码时添加一个名为
class
的参数。新的class
将添加到包裹<iframe>
的<div>
中,并删除其内联样式。请注意,您还需要将id
作为命名参数调用。您还可以使用title
为 Vimeo 视频添加描述性标题。
1
\{\{\< vimeo id="146022717" class="my-vimeo-wrapper-class" title="My vimeo video" \>\}\}
youtube
youtube
简码为 YouTube 视频嵌入一个响应式视频播放器。仅需要视频的 ID,例如:
|
|
youtube
输入 复制视频 URL 中 v=
后面的 YouTube 视频 ID 并将其传递给 youtube
简码:
example-youtube-input.md
|
|
此外,您可以将嵌入视频的autoplay
参数设置为 true
,以自动开始播放。请记住,您不能混合使用命名和未命名参数,因此您需要将未命名的视频 ID 分配给 id
参数:
example-youtube-input-with-autoplay.md
|
|
出于辅助功能的原因,最好为您的 YouTube 视频提供一个标题。您可以使用 title
参数为简码提供标题。如果没有提供标题,将使用默认标题"YouTube Video"。
example-youtube-input-with-title.md
|
|
youtube
输出 使用上述 youtube
示例,将添加以下 HTML 到您的站点的标记中:
example-youtube-output.html
|
|
youtube
显示** 使用上述 youtube
示例(不带 autoplay="true"
),以下是访问者在您的站点上看到的内容。当然,最终的显示将取决于您的样式表和周围的标记。该视频也包含在 Hugo 文档的快速入门中。
要了解如何配置您的Hugo站点以满足新的欧盟隐私法规,请参阅Hugo和GDPR。
要了解更多有关创建自定义简码的信息,请参阅简码模板文档。