引用块渲染钩子

上下文

引用块_渲染钩子_ 模板接收以下 上下文：

AlertType

(string) 当 Type 为 alert 时适用，这是转换为小写的警报类型。请参阅下面的 警报 部分。

AlertTitle

New in v0.134.0

(template.HTML) 当 Type 为 alert 时适用，这是警报名称。请参阅下面的 警报 部分。

AlertSign

New in v0.134.0

(string) 当 Type 为 alert 时适用，这是警报符号。通常用于指示警报是否可在图形上折叠，这是 +、- 或空字符串之一。请参阅下面的 警报 部分。

Attributes

(map) Markdown 属性，如果您的站点配置如下则可用：

markup:
  goldmark:
    parser:
      attribute:
        block: true

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      [markup.goldmark.parser.attribute]
        block = true

{
   "markup": {
      "goldmark": {
         "parser": {
            "attribute": {
               "block": true
            }
         }
      }
   }
}

Ordinal

(int) 页面上引用块的从零开始的序号。

Page

(page) 对当前页面的引用。

PageInner

(page) 对通过 RenderShortcodes 方法嵌套的页面的引用。详见。

Position

(string) 引用块在页面内容中的位置。

Text

(template.HTML) 引用块文本，如果 Type 为 alert 则不包括第一行。请参阅下面的 警报 部分。

Type

(string) 引用块类型。如果引用块具有警报指示符则返回 alert，否则返回 regular。请参阅下面的 警报 部分。

示例

在默认配置中，Hugo 根据 CommonMark 规范 渲染 Markdown 引用块。要创建执行相同操作的渲染钩子：

<blockquote>
  {{ .Text }}
</blockquote>

要将引用块渲染为带有可选引用和标题的 HTML figure 元素：

<figure>
  <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}>
    {{ .Text }}
  </blockquote>
  {{ with .Attributes.caption }}
    <figcaption class="blockquote-caption">
      {{ . | safeHTML }}
    </figcaption>
  {{ end }}
</figure>

然后在您的 Markdown 中：

> Some text
{cite="https://www.hugodoc.com" caption="Some caption"}

警报

警报也称为 callouts 或 admonitions，是用于强调关键信息的引用块。

基本语法

使用基本 Markdown 语法，每行警报的第一行是警报指示符，由感叹号后跟警报类型组成，并用括号包裹。例如：

> [!NOTE]
> 用户在浏览内容时应该了解的有用信息。

> [!TIP]
> 帮助更好地或更轻松地完成事情的建议。

> [!IMPORTANT]
> 用户实现目标需要了解的关键信息。

> [!WARNING]
> 需要用户立即注意以避免问题的紧急信息。

> [!CAUTION]
> 关于某些行动的风险或负面结果的警告。

基本语法与 GitHub、Obsidian 和 Typora 兼容。

扩展语法

使用扩展 Markdown 语法，您可以选择包含警报符号和/或警报名称。警报符号是 + 或 - 之一，通常用于指示警报是否可在图形上折叠。例如：

> [!WARNING]+ 辐射危险
> 请勿在没有防护装备的情况下靠近或处理。

扩展语法与 Obsidian 兼容。

示例

如果存在警报指示符，此引用块渲染钩子会渲染多语言警报，否则根据 CommonMark 规范渲染引用块。

{{ $emojis := dict
  "caution" ":exclamation:"
  "important" ":information_source:"
  "note" ":information_source:"
  "tip" ":bulb:"
  "warning" ":information_source:"
}}

{{ if eq .Type "alert" }}
  <blockquote class="alert alert-{{ .AlertType }}">
    <p class="alert-heading">
      {{ transform.Emojify (index $emojis .AlertType) }}
      {{ with .AlertTitle }}
        {{ . }}
      {{ else }}
        {{ or (i18n .AlertType) (title .AlertType) }}
      {{ end }}
    </p>
    {{ .Text }}
  </blockquote>
{{ else }}
  <blockquote>
    {{ .Text }}
  </blockquote>
{{ end }}

要覆盖标签，请在您的 i18n 文件中创建这些条目：

caution: 警告
important: 重要
note: 注意
tip: 提示
warning: 警告

caution = '警告'
important = '重要'
note = '注意'
tip = '提示'
warning = '警告'

{
   "caution": "警告",
   "important": "重要",
   "note": "注意",
   "tip": "提示",
   "warning": "警告"
}

虽然您可以使用一个带有条件逻辑的模板（如上所示），但您也可以为每种 Type 的引用块创建单独的模板：

layouts/
  └── _markup/
      ├── render-blockquote-alert.html
      └── render-blockquote-regular.html

PageInner 详情

PageInner 的主要用途是相对于包含的 Page 解析链接和 页面资源。例如，创建一个 “include” 短代码，从多个内容文件组合页面，同时保留脚注和目录的全局上下文：

{{ with .Get 0 }}
  {{ with $.Page.GetPage . }}
    {{- .RenderShortcodes }}
  {{ else }}
    {{ errorf "短代码 %q 无法找到 %q。参见 %s" $.Name . $.Position }}
  {{ end }}
{{ else }}
  {{ errorf "短代码 %q 需要一个位置参数来指示要包含的文件的逻辑路径。参见 %s" .Name .Position }}
{{ end }}

然后在您的 Markdown 中调用短代码：

{{% include "/posts/post-2" %}}

在渲染 /posts/post-2 时触发的任何渲染钩子将获得：

• 调用 Page 时获得 /posts/post-1
• 调用 PageInner 时获得 /posts/post-2

如果不相关，PageInner 会回退到 Page 的值，并且始终返回一个值。

作为实际示例，Hugo 的嵌入式链接和图像渲染钩子使用 PageInner 方法来解析 Markdown 链接和图像目标。请参阅各自的源代码：

• 嵌入式链接渲染钩子
• 嵌入式图像渲染钩子