Markdown渲染钩子

  4 分钟阅读  

Markdown Render Hooks - Markdown渲染钩子

https://gohugo.io/templates/render-hooks/

​ 渲染钩子允许自定义模板覆盖markdown渲染功能。

​ 请注意，这只支持Goldmark渲染器。

​ 您可以通过在layouts/_default/_markup中创建名称为render-{kind}的模板来覆盖默认的Markdown渲染为HTML的某些部分。

​ 您还可以在layouts/[type/section]/_markup中创建特定于type/section的钩子，例如：layouts/blog/_markup。

​ 目前支持的钩子种类有：

​ 如果需要，您可以定义特定于输出格式和语言的模板。您的layouts文件夹可能如下所示：

1
2
3
4
5
6
7
8
9

layouts/
└── _default/
    └── _markup/
        ├── render-codeblock-bash.html
        ├── render-codeblock.html
        ├── render-heading.html
        ├── render-image.html
        ├── render-image.rss.xml
        └── render-link.html

​ 以下是上述用法的一些示例：

  • 使用.GetPage解析链接引用。这将使链接可移植，因为您可以将./my-post.md（和在GitHub上可以使用的类似构造）转换为/blog/2019/01/01/my-post/等。
  • 为外部链接添加target=_blank。
  • 解析和处理图像。
  • 添加标题链接。

渲染钩子应用于标题、链接和图像

传递给render-link和render-image的上下文

​ render-link和render-image模板将接收到以下上下文：

  • Page

    正在被渲染的Page。

  • Destination

    The URL.

  • Title

    title属性。

  • Text

    渲染后的（HTML）链接文本。

  • PlainText

    上述文本的纯文本版本。

传递给render-heading的上下文

​ render-heading模板将接收以下上下文：

  • Page

    正在被渲染的页面。

  • Level

    标题级别（1-6）

  • Anchor

    在该页面中唯一的自动生成的HTML id。

  • Text

    被渲染后的（HTML）文本。

  • PlainText

    上述内容的纯文本版本。

  • Attributes (map)

    一个属性映射（例如id、class）。需要注意的是，对于链接，这个映射目前始终为空。

The render-image templates will also receive:

​ render-image模板还将接收：

带标题的Markdown链接示例

1

[Text](https://www.gohugo.io "Title")

​ 以下是render-link.html模板的代码示例：

layouts/_default/_markup/render-link.html

1

<a href="{{ .Destination | safeURL }}"{{ with .Title }} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>

图像Markdown示例

1

![Text](https://gohugo.io/images/hugo-logo-wide.svg "Title")

​ 以下是render-image.html模板的代码示例：

layouts/_default/_markup/render-image.html

1
2
3

<p class="md__image">
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title }} title="{{ . }}"{{ end }} />
</p>

标题链接示例

​ 给定此模板文件

layouts/_default/_markup/render-heading.html

1

<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>

​ 以及这个 markdown

1

### Section A

​ 渲染出的 HTML 代码将是

1

<h3 id="section-a">Section A <a href="#section-a">¶</a></h3>

代码块的渲染钩子

New in v0.93.0

​ 您可以为所有代码块或特定类型/语言（例如下面的bash）添加钩子模板：

image-20230425200136050

​ 这些代码块的默认行为是进行代码高亮，但是由于可以向这些代码块传递属性，因此它们可以用于几乎任何事情。一个示例是内置的GoAT Diagrams或这个Mermaid Diagram Code Block Hook示例。

​ 代码块模板中您可以获取到的上下文（"."）包括：

  • Type (string)

    代码块的类型。这将是编程语言，例如bash，用于进行代码高亮。

  • Attributes (map)

    从Markdown传递的属性（例如{ attrName1=attrValue1 attrName2="attr Value 2" }）。

  • Options (map)

    Chroma 高亮处理选项。仅在 Type 是已知的 Chroma Lexer 时才填充。

  • Inner (string)

    代码围栏之间的文本。

  • Ordinal (integer)

    当前文档中所有代码块的从零开始的序数。

  • Page

    所属的Page。

  • Position

    在错误日志中有用，因为它会打印出文件名和位置（行号、列号），例如 {{ errorf "error in code block: %s" .Position }}。

另请参阅

最后修改 May 22, 2023: 第一次提交 (9f24e27)