图片渲染钩子

Markdown

Markdown 图片有三个组成部分：图片描述、图片目标和可选的图片标题。

![white kitten](/images/kitten.jpg "A kitten!")
  ------------  ------------------  ---------
  description      destination        title

这些组件会传递到渲染钩子 上下文 中，如下所示。

上下文

图片_渲染钩子_ 模板接收以下上下文：

Attributes

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

markup:
  goldmark:
    parser:
      attribute:
        block: true
      wrapStandAloneImageWithinParagraph: false

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

{
   "markup": {
      "goldmark": {
         "parser": {
            "attribute": {
               "block": true
            },
            "wrapStandAloneImageWithinParagraph": false
         }
      }
   }
}

Destination

(string) 图片目标。

IsBlock

(bool) 报告独立图片是否未包裹在段落元素中。

Ordinal

(int) 页面上图片的从零开始的序号。

Page

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

PageInner

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

PlainText

(string) 图片描述（纯文本形式）。

Text

(template.HTML) 图片描述。

Title

(string) 图片标题。

示例

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

<img src="{{ .Destination | safeURL }}"
  {{- with .PlainText }} alt="{{ . }}"{{ end -}}
  {{- with .Title }} title="{{ . }}"{{ end -}}
>
{{- /* 删除尾随换行符 */ -}}

要在 figure 元素中渲染独立图片：

{{- if .IsBlock -}}
  <figure>
    <img src="{{ .Destination | safeURL }}"
      {{- with .PlainText }} alt="{{ . }}"{{ end -}}
    >
    {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}}
  </figure>
{{- else -}}
  <img src="{{ .Destination | safeURL }}"
    {{- with .PlainText }} alt="{{ . }}"{{ end -}}
    {{- with .Title }} title="{{ . }}"{{ end -}}
  >
{{- end -}}

请注意，上述需要以下站点配置：

markup:
  goldmark:
    parser:
      wrapStandAloneImageWithinParagraph: false

[markup]
  [markup.goldmark]
    [markup.goldmark.parser]
      wrapStandAloneImageWithinParagraph = false

{
   "markup": {
      "goldmark": {
         "parser": {
            "wrapStandAloneImageWithinParagraph": false
         }
      }
   }
}

嵌入式

Hugo 包含一个 嵌入式图片渲染钩子 来解析 Markdown 图片目标。您可以在站点配置中调整其行为。这是默认设置：

markup:
  goldmark:
    renderHooks:
      image:
        useEmbedded: auto

[markup]
  [markup.goldmark]
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.image]
        useEmbedded = 'auto'

{
   "markup": {
      "goldmark": {
         "renderHooks": {
            "image": {
               "useEmbedded": "auto"
            }
         }
      }
   }
}

如上所示设置为 auto 时，Hugo 会自动为多语言单主机站点使用嵌入式图片渲染钩子，特别是在 共享页面资源复制 功能被禁用时。这是此类站点的默认行为。如果您的项目、模块或主题定义了自定义图片渲染钩子，则会使用这些钩子。

您还可以配置 Hugo always（始终）使用嵌入式图片渲染钩子、仅作为 fallback（后备）使用，或 never（从不）使用。请参阅 详情。

嵌入式图片渲染钩子通过查找匹配的 页面资源 来解析内部 Markdown 目标，如果找不到则回退到匹配的 全局资源。远程目标会直接传递，如果无法解析目标，渲染钩子不会抛出错误或警告。

您必须将全局资源放在 assets 目录中。如果您已将资源放在 static 目录中，并且无法或不愿移动它们，则必须通过在站点配置中包含以下两个条目，将 static 目录挂载到 assets 目录：

module:
  mounts:
  - source: assets
    target: assets
  - source: static
    target: assets

[module]
  [[module.mounts]]
    source = 'assets'
    target = 'assets'
  [[module.mounts]]
    source = 'static'
    target = 'assets'

{
   "module": {
      "mounts": [
         {
            "source": "assets",
            "target": "assets"
         },
         {
            "source": "static",
            "target": "assets"
         }
      ]
   }
}

请注意，嵌入式图片渲染钩子不执行图片处理。其唯一目的是解析 Markdown 图片目标。

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 链接和图像目标。请参阅各自的源代码：

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