Markdown渲染钩子

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-linkrender-image的上下文

render-linkrender-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)

    一个属性映射(例如idclass)。需要注意的是,对于链接,这个映射目前始终为空。

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)