Shortcodes：内建与自定义实现方法

Shortcodes 是 Hugo 强大的内容管理功能之一，旨在简化和标准化内容的创建，允许用户在 Markdown 或其他内容格式中插入复杂元素，而无需直接编写 HTML 或复杂的模板逻辑。Hugo 作为一个用 Go 语言编写的静态站点生成器，以其速度和灵活性而闻名。Shortcodes 很好地体现了 Hugo 在内容创作方面的灵活性和强大功能。

Shortcodes 的定义与目的

Shortcodes 是一种内嵌在内容文件中的特殊代码片段，用于插入预定义的、可重用的内容或逻辑。它们将复杂的功能抽象化，使得内容作者可以专注于写作，而不需要处理底层的 HTML 或 Go Template 语法。例如，它们可以用于嵌入音频/视频播放器、图片库、图表、地图或从数据源渲染表格等。

Shortcodes 的类型

Hugo 支持三种类型的 Shortcodes：

嵌入式 Shortcodes（Embedded Shortcodes）

这些是 Hugo 内置的、预定义好的模板，用于许多常见任务。

例如，Hugo 内置了 details、figure、gist、highlight、instagram、param、QR、ref、relref、vimeo、X (Twitter) 和 YouTube 等 Shortcodes。

其中一些 Shortcodes，例如 gist，可能已被弃用，文档建议用户创建自定义 Shortcode 来替代其功能。

用户可以通过复制其源代码到 layouts/shortcodes 或 layouts/_shortcodes 目录来覆盖 Hugo 内置的 Shortcode。需要注意的是，在较早版本的 Hugo 中使用的是 layouts/shortcodes 目录，而在较新版本中建议使用 layouts/_shortcodes 目录。

自定义 Shortcodes（Custom Shortcodes）

用户可以根据自己的特定需求创建自定义 Shortcodes，以简化和标准化内容创建。

目录结构：自定义 Shortcodes 模板创建在 layouts/_shortcodes 目录下，可以是根目录或子目录。

查找顺序：Hugo 会根据 Shortcode 名称、当前输出格式和语言来选择 Shortcode 模板，优先级从最具体到最不具体。

模板内部：Shortcode 模板可以使用变量、函数和方法来处理传入的数据。例如，Page 方法可以访问调用 Shortcode 的页面对象，Params 方法可以访问 Shortcode 参数，Inner 方法可以获取 Shortcode 标签之间的内容。Ordinal 方法可用于为 Shortcode 渲染的元素分配唯一的 ID。

内联 Shortcodes（Inline Shortcodes）

内联 Shortcode 是直接在内容中定义的 Shortcode 模板。

出于安全考虑，默认情况下禁用此功能，因为 Hugo 的安全模型信任模板和配置作者，但不信任内容作者。如果信任内容作者，可以通过配置 security.enableInlineShortcodes = true 来启用。

内联 Shortcodes 不能嵌套。

调用 Shortcodes

Shortcode 调用涉及三个句法元素：标签 (tags)、参数 (arguments) 和符号 (notation)。

标签

• 有些 Shortcodes 需要开放和封闭标签，例如 < figure >< /figure >。
• 有些 Shortcodes 不接受内容，只接受参数，例如 < gist ID >。
• 有些 Shortcodes 可以选择性地接受内容，可以使用自闭合语法 (< figure src="image.jpg" >) 或开放/封闭标签 (< figure src="image.jpg" >Caption< /figure >)。

参数

Shortcode 参数可以是命名参数 (named arguments) 或位置参数 (positional arguments)。

• 命名参数以键值对形式传递（例如 src="image.jpg"），而位置参数则根据其在调用中的位置确定。
• 在一个 Shortcode 调用中，命名参数和位置参数不能混合使用。
• 在 Shortcode 模板中，可以使用 SHORTCODE.Get 方法通过位置或名称检索参数。SHORTCODE.IsNamedParams 方法可以判断 Shortcode 调用是否使用了命名参数。SHORTCODE.Params 方法可以返回 Shortcode 参数的集合，对于命名参数返回 map，对于位置参数返回 slice。

符号（Notation）

Shortcode 可以使用两种不同的符号调用：Markdown 符号和标准符号。

• Markdown 符号 (% shortcode % 或 % shortcode /%)：Hugo 在 Markdown 渲染器处理页面内容之前处理 Shortcode。这意味着 Shortcode 内的 Markdown 标题将包含在 Page.TableOfContents 方法的输出中。
• 标准符号 (< shortcode > 或 < shortcode />)：Hugo 单独处理 Shortcode，然后在 Markdown 渲染后将输出合并到页面内容中。这意味着 Shortcode 内的 Markdown 标题将不包含在 Page.TableOfContents 方法的输出中。

与 Shortcodes 相关的重要概念与功能

Shortcode 对象方法

在自定义 Shortcode 模板中，你可以使用 SHORTCODE 对象的各种方法来处理参数和内容。关于这些方法的详细信息，请参见模板方法章节中的 Shortcode 对象方法部分。

上下文（Context）

理解模板上下文对于编写 Shortcode 模板至关重要。在 Shortcode 模板中，. 通常代表当前 Shortcode 对象，而 $ 代表从顶层模板传入的页面对象。

嵌套（Nesting）

Shortcodes（内联 Shortcodes 除外）可以嵌套，形成父子关系。SHORTCODE.Parent 方法允许访问父 Shortcode 的上下文，这对于参数继承很有用。

错误报告

Shortcode 提供了 SHORTCODE.Name 和 SHORTCODE.Position 方法，有助于在 Shortcode 调用失败时提供错误报告，例如缺少必需参数时。

检测 Shortcode 使用

Page.HasShortcode 方法可以判断特定 Shortcode 是否在页面中被调用，这使得可以有条件地加载特定 Shortcode 所需的 CSS 或 JavaScript。

存储数据（Scratchpad）

Page.Store 和 SHORTCODE.Store 方法（过去称为 Scratch）提供了"临时存储空间"，用于存储和操作页面或 Shortcode 范围内的数据。这对于在 Shortcode、Partial 模板或 Markdown 渲染钩子中设置值非常有用。

渲染 Shortcodes（RenderShortcodes）

Page.RenderShortcodes 方法用于渲染给定页面内容中的所有 Shortcodes，同时保留周围的标记。这在通过 Shortcode 组合多个内容文件时非常有用。

渲染钩子（Render Hooks）

Hugo 的渲染钩子可以覆盖 Markdown 到 HTML 的转换。虽然 Shortcodes 和渲染钩子是不同的功能，但它们都处理内容渲染。例如，transform.Markdownify 函数可以处理 Markdown 并尊重渲染钩子，但如果渲染钩子访问 .Page 上下文，建议使用 RenderString 方法。

安全模型（Security Model）

Hugo 的安全模型基于信任模板和配置作者，但不信任内容作者。这对于防止代码注入至关重要。因此，默认情况下禁用内联 Shortcodes，需要明确启用。

国际化/多语言支持（Multilingual Support）

Shortcode 模板可以根据语言进行本地化。

资产管道和资源处理（Asset Pipelines & Resource Processing）

Shortcodes 可以与 Hugo Pipes 和图像处理功能结合使用，例如通过 images.QR 函数生成 QR 码，或通过 resources.GetMatch 等函数获取和处理图像资源。

总结

Shortcodes 是 Hugo 框架中一个极其灵活和强大的组成部分，它允许用户在静态站点中实现接近动态网站的功能，而又无需牺牲性能和安全性。通过内置 Shortcodes、自定义 Shortcodes 和内联 Shortcodes，Hugo 为内容作者提供了极大的便利，使他们能够轻松地插入复杂的、可重用的内容片段，极大地提升了内容创作的效率和站点的表现力。

理解 Shortcodes 的调用方式、参数处理、上下文以及与 Hugo 其他功能的集成方式，是充分利用 Hugo 创建功能丰富且易于维护的静态网站的关键。