HUGO 中文文档

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
gohugoio Star
  • 关于
    • 本节内容
    • 简介
    • 特性
    • 隐私
    • 安全
    • 许可证
  • 安装
    • 本节内容
    • macOS
    • Linux
    • Windows
    • BSD
  • 快速上手
    • 本节内容
    • 快速入门
    • 基本用法
    • 目录结构
    • 配置
    • 配置标记
    • 术语表
    • 配置构建
    • 外部学习资源
  • 快速参考
    • 本节内容
    • 表情符号
    • 函数
    • 方法
    • 页面集合
  • 内容管理
    • 本节内容
    • 组织
    • 页面包
    • 内容格式
    • Front matter (前置 matter)
    • 构建选项
    • 页面资源
    • 图片处理
    • 短代码
    • 相关内容
    • 章节
    • 内容类型
    • 原型
    • 分类法
    • 摘要
    • 链接和交叉引用
    • URL 管理
    • 菜单
    • 评论
    • 多语言
    • Markdown 属性
    • 语法高亮
    • 图表
    • 数学公式
    • 数据源
    • 内容适配器
  • 模板
    • 本节内容
    • 简介
    • 模板类型
    • 查找顺序
    • 基模板
    • 首页模板
    • 单个模板
    • 章节模板
    • 分类模板
    • 术语模板
    • 局部模板
    • 内容视图模板
    • 短代码模板
    • 站点地图模板
    • RSS 模板
    • 404 模板
    • robots.txt 模板
    • 菜单
    • 分页
    • 内嵌模板
    • 自定义输出格式
  • 函数
    • 本节内容
    • css
    • fmt
    • go 模板
    • hugo
    • js
    • lang
    • openapi3
    • os
    • urls
    • 全局
    • 加密
    • 反射
    • 变形
    • 变换
    • 哈希
    • 图像
    • 图表函数
    • 字符串
    • 安全函数
    • 局部模板函数
    • 数学
    • 数据
    • 时间
    • 模板
    • 比较
    • 类型转换
    • 编码
    • 调试
    • 资源
    • 路径
    • 集合
  • 方法
    • 本节内容
    • Duration
    • Menu
    • Page
    • Pager
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
    • 菜单项
    • 页面
  • 渲染钩子
    • 本节内容
    • 简介
    • 块引用
    • 代码块
    • 标题
    • Images
    • 链接
    • Passthrough
    • 表格
  • Hugo 模块
    • 本节内容
    • 配置 Hugo 模块
    • 使用 Hugo 模块
    • 主题组件
  • Hugo 管道
    • 本节内容
    • 简介
    • 将 Sass 编译为 CSS
    • PostCSS
    • PostProcess
    • JavaScript 构建
    • 资源压缩
    • 连接资产
    • 指纹和 SRI 哈希
    • 从字符串创建资源
    • 从模板创建资源
  • 命令行界面
  • 故障排除
    • 本节内容
    • Audit
    • 日志记录
    • 检查
    • 弃用
    • 性能
    • FAQs
  • 开发者工具
    • 本节内容
    • 编辑器插件
    • 前端
    • Search
    • 迁移
    • 其他项目
  • 托管和部署
    • 本节内容
    • Hugo 部署
    • 使用 Rclone 部署
    • 使用 Rsync 部署
    • 在 21YunBox 上托管
    • 在 AWS Amplify 上托管
    • 在 Cloudflare Pages 上托管
    • 在 Firebase 上托管
    • 在 GitLab Pages 上托管
    • 在 Netlify 上托管
    • 在 Render 上托管
    • 托管在 Azure 静态 Web 应用上
    • 托管在 GitHub Pages 上
    • 托管在 KeyCDN 上
  • 贡献
    • 本节内容
    • 开发
    • 文档
    • 主题
  • 维护
TEMPLATES

创建你自己的短代码

你可以使用与单页和列表页相同的模板语法来创建你自己的短代码,从而扩展 Hugo 的嵌入式短代码。

短代码是一种将模板整合到小型、可重用代码片段中的方法,您可以直接将其嵌入到内容中。

Hugo 还附带了用于常见用例的嵌入式短代码。(参见 内容管理:短代码 。)

创建自定义短代码

Hugo 的嵌入式短代码涵盖了许多常见用例,但并非所有用例。幸运的是,Hugo 提供了轻松创建自定义短代码以满足您网站需求的功能。

文件位置

要创建短代码,请将 HTML 模板放在 layouts/shortcodes 目录中。仔细考虑文件名,因为短代码名称将与文件名相同,但没有 .html 扩展名。例如, layouts/shortcodes/myshortcode.html 将使用 {{< myshortcode />}} 或 {{% myshortcode /%}} 调用。

您可以将短代码组织到子目录中,例如在 layouts/shortcodes/boxes 中。然后可以使用它们的相对路径访问这些短代码,例如:

{{< boxes/square >}}

请注意正斜杠。

模板查找顺序

Hugo 根据短代码名称、当前输出格式和当前语言选择短代码模板。以下示例按特异性降序排列。列表底部是最不具体的路径。

短代码名称 输出格式 语言 模板路径
foo html en layouts/shortcodes/foo.en.html
foo html en layouts/shortcodes/foo.html.html
foo html en layouts/shortcodes/foo.html
foo html en layouts/shortcodes/foo.html.en.html
短代码名称 输出格式 语言 模板路径
foo rss en layouts/shortcodes/foo.en.xml
foo rss en layouts/shortcodes/foo.rss.xml
foo rss en layouts/shortcodes/foo.en.html
foo rss en layouts/shortcodes/foo.rss.en.xml
foo rss en layouts/shortcodes/foo.xml
foo rss en layouts/shortcodes/foo.html.en.html
foo rss en layouts/shortcodes/foo.html.html
foo rss en layouts/shortcodes/foo.html

请注意,主题或模块提供的模板始终优先。

位置参数与命名参数

您可以使用以下类型的参数创建短代码:

  • 位置参数
  • 命名参数
  • 位置参数 或 命名参数

在使用位置参数的短代码中,参数的顺序很重要。如果短代码只有一个必需的值,则位置参数需要内容作者较少的输入。

对于具有多个或可选参数的更复杂的布局,命名参数最有效。虽然不如简洁,但命名参数需要内容作者记住的内容更少,并且可以在短代码声明中以任何顺序添加。

允许这两种类型的参数对于复杂的布局非常有用,在这些布局中,您希望设置可以由用户轻松覆盖的默认值。

访问参数

所有短代码参数都可以通过 .Get 方法访问。您是将字符串还是数字传递给 .Get 方法取决于您是访问命名参数还是位置参数。

要按名称访问参数,请使用 .Get 方法,后跟作为带引号的字符串的命名参数:

{{ .Get "class" }}

要按位置访问参数,请使用 .Get 方法,后跟一个数字位置,请记住位置参数是从零开始的:

{{ .Get 0 }}

对于第二个位置,您只需使用:

{{ .Get 1 }}

当输出取决于设置的参数时, with 非常有用:

{{ with .Get "class" }} class="{{ . }}"{{ end }}

.Get 还可以用于检查是否已提供参数。当条件取决于任一值或两者时,这最有用:

{{ if or (.Get "title") (.Get "alt") }} alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "title" }}{{ end }}"{{ end }}

.Inner

.Inner 方法返回开始和结束短代码标记之间的内容。要检查 .Inner 是否返回除空格以外的其他内容:

{{ if strings.ContainsNonSpace .Inner }}
  Inner is not empty
{{ end }}

任何调用 .Inner 方法的短代码都必须关闭或自闭合。要使用自闭合语法调用短代码。

{{< innershortcode />}}

.Params

短代码中的 .Params 方法返回传递给短代码的参数,用于更复杂的用例。您还可以使用以下逻辑访问范围更高的参数:

$.Params
这些是直接传递到短代码声明中的参数(例如,YouTube 视频 ID)
$.Page.Params
指的是页面的参数;此处的“页面”指的是声明短代码的内容文件(例如,内容前题中 shortcode_color 字段可以通过 $.Page.Params.shortcode_color 访问)。
$.Site.Params
指的是在您的站点配置中定义的参数。

.IsNamedParams

.IsNamedParams 方法检查短代码声明是否使用命名参数并返回布尔值。

例如,您可以创建一个 image 短代码,它可以采用 src 命名参数或第一个位置参数,具体取决于内容作者的偏好。让我们假设 image 短代码如下调用:

{{< image src="images/my-image.jpg" >}}

然后您可以将以下内容包含在您的短代码模板中:

{{ if .IsNamedParams }}
  <img src="{{ .Get "src" }}" alt="">
{{ else }}
  <img src="{{ .Get 0 }}" alt="">
{{ end }}

请参见下面的 示例 Vimeo 短代码 ,了解 .IsNamedParams 的实际应用。

虽然您可以创建接受位置参数和命名参数的短代码模板,但您不能使用混合参数类型的声明内容中的短代码。因此,像 {{< image src="images/my-image.jpg" "This is my alt text" >}} 这样声明的短代码将返回错误。

短代码也可以嵌套。在嵌套短代码中,您可以使用 .Parent 短代码方法访问父短代码上下文。这对于从根继承非常有用。

检查是否存在

您可以通过在该页面模板中调用 .HasShortcode 并提供短代码的名称来检查页面上是否使用了特定短代码。当您想要在标题中包含仅由该短代码使用的特定脚本或样式时,这非常有用。

自定义短代码示例

以下是您可以通过 /layouts/shortcodes 中的短代码模板文件创建的不同类型的短代码示例。

单词示例: year

让我们假设您希望在内容文件中保持版权年份的提及最新,而无需不断检查您的 Markdown。您的目标是能够按如下方式调用短代码:

{{< year >}}
layouts/shortcodes/year.html
{{ now.Format "2006" }}

单个位置参数示例: youtube

嵌入式视频是 Markdown 内容的常见补充。以下是 Hugo 的内置 YouTube 短代码 使用的代码:

{{< youtube 09jf3ow9jfw >}}

将加载 /layouts/shortcodes/youtube.html 中的模板:

layouts/shortcodes/youtube.html
<div class="embed video-player">
<iframe class="youtube-player" type="text/html" width="640" height="385" src="https://www.youtube.com/embed/{{ index .Params 0 }}" allowfullscreen frameborder="0">
</iframe>
</div>
youtube-embed.html
<div class="embed video-player">
    <iframe class="youtube-player" type="text/html"
        width="640" height="385"
        src="https://www.youtube.com/embed/09jf3ow9jfw"
        allowfullscreen frameborder="0">
    </iframe>
</div>

单个命名参数示例: image

假设您想创建自己的 img 短代码,而不是使用 Hugo 的内置 figure 短代码 。您的目标是能够在内容文件中按如下方式调用短代码:

content-image.md
{{< img src="/media/spf13.jpg" title="Steve Francia" >}}

您已在 /layouts/shortcodes/img.html 中创建了短代码,该短代码加载以下短代码模板:

layouts/shortcodes/img.html
<!-- image -->
<figure {{ with .Get "class" }}class="{{ . }}"{{ end }}>
  {{ with .Get "link" }}<a href="{{ . }}">{{ end }}
    <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt" }}{{ . }}{{ else }}{{ .Get "caption" }}{{ end }}"{{ end }} />
    {{ if .Get "link" }}</a>{{ end }}
    {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr") }}
      <figcaption>{{ if isset .Params "title" }}
        <h4>{{ .Get "title" }}</h4>{{ end }}
        {{ if or (.Get "caption") (.Get "attr") }}<p>
        {{ .Get "caption" }}
        {{ with .Get "attrlink" }}<a href="{{ . }}"> {{ end }}
          {{ .Get "attr" }}
        {{ if .Get "attrlink" }}</a> {{ end }}
        </p> {{ end }}
      </figcaption>
  {{ end }}
</figure>
<!-- image -->

将呈现为:

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

单个灵活示例: vimeo

{{< vimeo 49718712 >}}
{{< vimeo id="49718712" class="flex-video" >}}

将加载在 /layouts/shortcodes/vimeo.html 中找到的模板:

layouts/shortcodes/vimeo.html
{{ if .IsNamedParams }}
  <div class="{{ if .Get "class" }}{{ .Get "class" }}{{ else }}vimeo-container{{ end }}">
    <iframe src="https://player.vimeo.com/video/{{ .Get "id" }}" allowfullscreen></iframe>
  </div>
{{ else }}
  <div class="{{ if len .Params | eq 2 }}{{ .Get 1 }}{{ else }}vimeo-container{{ end }}">
    <iframe src="https://player.vimeo.com/video/{{ .Get 0 }}" allowfullscreen></iframe>
  </div>
{{ end }}

将呈现为:

vimeo-iframes.html
<div class="vimeo-container">
  <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
</div>
<div class="flex-video">
  <iframe src="https://player.vimeo.com/video/49718712" allowfullscreen></iframe>
</div>

配对示例: highlight

以下内容取自 highlight ,它是 Hugo 附带的 内置短代码 。

highlight-example.md
{{< highlight html >}}
  <html>
    <body> This HTML </body>
  </html>
{{< /highlight >}}

highlight 短代码的模板使用以下代码,该代码已包含在 Hugo 中:

{{ .Get 0 | highlight .Inner }}

HTML 示例代码块的呈现输出如下所示:

syntax-highlighted.html
<div class="highlight" style="background: #272822"><pre style="line-height: 125%"><span style="color: #f92672">&lt;html&gt;</span>
    <span style="color: #f92672">&lt;body&gt;</span> This HTML <span style="color: #f92672">&lt;/body&gt;</span>
<span style="color: #f92672">&lt;/html&gt;</span>
</pre></div>

嵌套短代码:图片库

Hugo 的 .Parent 短代码方法在相关短代码在父短代码的上下文中调用时,提供对父短代码上下文的访问。这提供了一种继承模型。

以下示例是人为编造的,但演示了这个概念。假设您有一个 gallery 短代码,它期望一个名为 class 的参数:

layouts/shortcodes/gallery.html
<div class="{{ .Get "class" }}">
  {{ .Inner }}
</div>

您还有一个 img 短代码,它只有一个名为 src 的参数,您希望在 gallery 和其他短代码内调用它,以便父级定义每个 img 的上下文:

layouts/shortcodes/img.html
{{- $src := .Get "src" -}}
{{- with .Parent -}}
  <img src="{{ $src }}" class="{{ .Get "class" }}-image">
{{- else -}}
  <img src="{{ $src }}">
{{- end -}}

然后,您可以按如下方式在内容中调用您的短代码:

{{< gallery class="content-gallery" >}}
  {{< img src="/images/one.jpg" >}}
  {{< img src="/images/two.jpg" >}}
{{< /gallery >}}
{{< img src="/images/three.jpg" >}}

这将输出以下 HTML。请注意,前两个 img 短代码继承了通过对父 gallery 的调用设置的 content-gallery 的 class 值,而第三个 img 只使用 src :

<div class="content-gallery">
    <img src="/images/one.jpg" class="content-gallery-image">
    <img src="/images/two.jpg" class="content-gallery-image">
</div>
<img src="/images/three.jpg">

短代码中的错误处理

使用 errorf 模板函数和 Name 和 Position 短代码方法来生成有用的错误消息:

layouts/shortcodes/greeting.html
{{ with .Get "name" }}
  <p>Hello, my name is {{ . }}.</p>
{{ else }}
  {{ errorf "The %q shortcode requires a 'name' argument. See %s" .Name .Position }}
{{ end }}

当上述操作失败时,您将看到类似以下的 ERROR 消息:

ERROR The "greeting" shortcode requires a 'name' argument. See "/home/user/project/content/_index.md:12:1"

行内短代码

您也可以在行内实现您的短代码——例如,在您使用它们的 Content 文件中。这对于您只需要在一个地方使用的脚本很有用。

此功能默认情况下是禁用的,但可以在您的站点配置中启用:

hugo.
     
security:
  enableInlineShortcodes: true
[security]
  enableInlineShortcodes = true
{
   "security": {
      "enableInlineShortcodes": true
   }
}

出于安全原因,它默认情况下是禁用的。Hugo 模板处理使用的安全模型假设模板作者是可信的,但内容文件不可信,因此模板可以防止格式错误的输入数据注入。但在大多数情况下,您也完全控制内容,那么 enableInlineShortcodes = true 将被认为是安全的。但这是一件需要注意的事情:它允许从内容文件中执行即席的 Go 文本模板 。

启用后,您可以在内容文件中执行此操作:

{{< time.inline >}}{{ now }}{{< /time.inline >}}

以上将打印当前日期和时间。

请注意,行内短代码的内部内容将被解析并作为 Go 文本模板执行,其上下文与常规短代码模板相同。

这意味着可以通过 .Page.Title 等访问当前页面。这也意味着没有“嵌套行内短代码”的概念。

如果需要,可以使用自闭合语法在同一个内容文件中稍后重用相同的行内短代码,并使用不同的参数:

{{< time.inline />}}

See also

  • Front matter (前置 matter)
  • Passthrough
  • 代码块
  • 短代码

On this page

  • 创建自定义短代码
  • 自定义短代码示例
  • 短代码中的错误处理
  • 行内短代码
Last updated: January 10, 2025: 添加 gtm 谷歌代码管理 (6220bf5)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2025.

The Hugo Gopher is based on an original work by Renée French.

  • 新闻
  • 文档
  • 主题
  • 社区
  • GitHub
  • 关于
  • 安装
  • 快速上手
  • 快速参考
  • 内容管理
  • 模板
  • 函数
  • 方法
  • 渲染钩子
  • Hugo 模块
  • Hugo 管道
  • 命令行界面
  • 故障排除
  • 开发者工具
  • 托管和部署
  • 贡献
  • 维护