Shortcode 方法 on Hugo 中文文档

Get

Fri, 02 Oct 2026 00:00:00 +0800

参数可以按位置或按名称指定。在 Markdown 中调用短代码时，位置参数和命名参数只能用其中一种，不能混用。

位置参数

下面这个短代码调用使用位置参数：

content/about.md

{{< myshortcode "Hello" "world" >}}

要按位置获取参数：

Inner

Fri, 02 Oct 2026 00:00:00 +0800

这段内容：

content/services.md

{{< card title="Product Design" >}}
We design the **best** widgets in the world.
{{< /card >}}

配上这个短代码：

layouts/_shortcodes/card.html

<div class="card">
  {{ with .Get "title" }}
    <div class="card-title">{{ . }}</div>
  {{ end }}
  <div class="card-content">
    {{ .Inner | strings.TrimSpace }}
  </div>
</div>

渲染结果为：

<div class="card">
  <div class="card-title">Product Design</div>
  <div class="card-content">
    We design the **best** widgets in the world.
  </div>
</div>

InnerDeindent

Fri, 02 Oct 2026 00:00:00 +0800

与 Inner 方法类似，InnerDeindent 返回短代码开始标签与结束标签之间的内容。不过，InnerDeindent 会移除内容前面的缩进。

这样我们就能有效绕过 CommonMark 规范中关于缩进的规则。

IsNamedParams

Fri, 02 Oct 2026 00:00:00 +0800

要让短代码调用同时支持位置参数和命名参数，可以用 IsNamedParams 方法判断短代码是以哪种方式调用的。

使用这个_短代码_模板：

layouts/_shortcodes/myshortcode.html

{{ if .IsNamedParams }}
  {{ printf "%s %s." (.Get "greeting") (.Get "firstName") }}
{{ else }}
  {{ printf "%s %s." (.Get 0) (.Get 1) }}
{{ end }}

下面两个调用返回相同的值：

Name

Fri, 02 Oct 2026 00:00:00 +0800

Name 方法在报告错误时很有用。例如，如果你的短代码需要一个「greeting」参数：

layouts/_shortcodes/myshortcode.html

{{ $greeting := "" }}
{{ with .Get "greeting" }}
  {{ $greeting = . }}
{{ else }}
  {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
{{ end }}

在没有「greeting」参数时，Hugo 会抛出错误消息并让构建失败：

Ordinal

Fri, 02 Oct 2026 00:00:00 +0800

Ordinal 方法返回短代码相对于其父级的从零开始的序号。如果父级就是页面本身，该序号表示这个短代码在页面内容中的位置。

Page

Fri, 02 Oct 2026 00:00:00 +0800

内容如下：

title = 'Les Misérables'
author = 'Victor Hugo'
publication_year = 1862
isbn = '978-0451419439'

调用这个短代码：

{{< book-details >}}

我们可以用 Page 方法访问前置元数据中的值：

layouts/_shortcodes/book-details.html

<ul>
  <li>Title: {{ .Page.Title }}</li>
  <li>Author: {{ .Page.Params.author }}</li>
  <li>Published: {{ .Page.Params.publication_year }}</li>
  <li>ISBN: {{ .Page.Params.isbn }}</li>
</ul>

Params

Fri, 02 Oct 2026 00:00:00 +0800

用位置参数调用短代码时，Params 方法返回一个切片。

content/about.md

{{< myshortcode "Hello" "world" >}}

layouts/_shortcodes/myshortcode.html

{{ index .Params 0 }} → Hello
{{ index .Params 1 }} → world

用命名参数调用短代码时，Params 方法返回一个映射。

Parent

Fri, 02 Oct 2026 00:00:00 +0800

这对于从根级继承公共的短代码参数很有用。

在这个刻意构造的示例中，「greeting」短代码是父级，「now」短代码是子级。

content/welcome.md

{{< greeting dateFormat="Jan 2, 2006" >}}
Welcome. Today is {{< now >}}.
{{< /greeting >}}

layouts/_shortcodes/greeting.html

<div class="greeting">
  {{ .Inner | strings.TrimSpace | .Page.RenderString }}
</div>

layouts/_shortcodes/now.html

{{- $dateFormat := "January 2, 2006 15:04:05" }}

{{- with .Params }}
  {{- with .dateFormat }}
    {{- $dateFormat = . }}
  {{- end }}
{{- else }}
  {{- with .Parent.Params }}
    {{- with .dateFormat }}
      {{- $dateFormat = . }}
    {{- end }}
  {{- end }}
{{- end }}

{{- now | time.Format $dateFormat -}}

「now」短代码按下面的顺序格式化当前时间：

Position

Fri, 02 Oct 2026 00:00:00 +0800

Position 方法在报告错误时很有用。例如，如果你的短代码需要一个「greeting」参数：

layouts/_shortcodes/myshortcode.html

{{ $greeting := "" }}
{{ with .Get "greeting" }}
  {{ $greeting = . }}
{{ else }}
  {{ errorf "The %q shortcode requires a 'greeting' argument. See %s" .Name .Position }}
{{ end }}

在没有「greeting」参数时，Hugo 会抛出错误消息并让构建失败：

Ref

Fri, 02 Oct 2026 00:00:00 +0800

用法

Ref 方法需要单个参数：一个选项映射。

选项

path: （string）目标页面的路径。不以斜杠（/）开头的路径先相对于当前页面解析，再相对于站点的其余部分解析。
lang: （string）目标页面的语言。默认是当前语言。可选。
outputFormat: （string）目标页面的输出格式。默认是当前输出格式。可选。

示例

下面的示例展示了站点英文版本中某个页面的渲染输出：

RelRef

Fri, 02 Oct 2026 00:00:00 +0800

用法

RelRef 方法需要单个参数：一个选项映射。

选项

path: （string）目标页面的路径。不以斜杠（/）开头的路径先相对于当前页面解析，再相对于站点的其余部分解析。
lang: （string）目标页面的语言。默认是当前语言。可选。
outputFormat: （string）目标页面的输出格式。默认是当前输出格式。可选。

示例

下面的示例展示了站点英文版本中某个页面的渲染输出：

Scratch

Fri, 02 Oct 2026 00:00:00 +0800

（0.139.0 起弃用）

请改用 SHORTCODE.Store 方法。

这是一次软弃用。该方法会在将来的某个版本中移除，但移除日期尚未确定。尽管你继续使用该方法时 Hugo 不会发出警告，但你应该尽快开始使用 SHORTCODE.Store。

Site

Fri, 02 Oct 2026 00:00:00 +0800

参见 Site 方法。

{{ .Site.Title }}

Store

Fri, 02 Oct 2026 00:00:00 +0800

（0.139.0 新增）

用 Store 方法可以创建一个持久化的数据结构，用于存储和操作带 key 的值，作用域为当前短代码。要创建其他作用域的数据结构，请参见下面的作用域一节。