passthrough.md - hugo - [fork] hugo port for 9front
(HTM) git clone https://git.drkhsh.at/hugo.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Submodules
(DIR) README
(DIR) LICENSE
---
passthrough.md (4494B)
---
1 ---
2 title: Passthrough render hooks
3 linkTitle: Passthrough
4 description: Create a passthrough render hook to override the rendering of text snippets captured by the Goldmark Passthrough extension.
5 categories: []
6 keywords: []
7 ---
8
9 {{< new-in 0.132.0 />}}
10
11 ## Overview
12
13 Hugo uses [Goldmark] to render Markdown to HTML. Goldmark supports custom extensions to extend its core functionality. The [Passthrough] extension captures and preserves raw Markdown within delimited snippets of text, including the delimiters themselves. These are known as _passthrough elements_.
14
15 [Goldmark]: https://github.com/yuin/goldmark
16 [Passthrough]: /configuration/markup/#passthrough
17
18 Depending on your choice of delimiters, Hugo will classify a passthrough element as either _block_ or _inline_. Consider this contrived example:
19
20 ```text {file="content/example.md"}
21 This is a
22
23 \[block\]
24
25 passthrough element with opening and closing block delimiters.
26
27 This is an \(inline\) passthrough element with opening and closing inline delimiters.
28 ```
29
30 Update your site configuration to enable the Passthrough extension and define opening and closing delimiters for each passthrough element type, either `block` or `inline`. For example:
31
32 {{< code-toggle file=hugo >}}
33 [markup.goldmark.extensions.passthrough]
34 enable = true
35 [markup.goldmark.extensions.passthrough.delimiters]
36 block = [['\[', '\]'], ['$$', '$$']]
37 inline = [['\(', '\)']]
38 {{< /code-toggle >}}
39
40 In the example above there are two sets of `block` delimiters. You may use either one in your Markdown.
41
42 The Passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in the LaTeX markup language.
43
44 [mathematical expressions]: /content-management/mathematics/
45
46 To enable custom rendering of passthrough elements, create a passthrough render hook.
47
48 ## Context
49
50 Passthrough render hook templates receive the following [context](g):
51
52 Attributes
53 : (`map`) The [Markdown attributes], available if you configure your site as follows:
54
55 {{< code-toggle file=hugo >}}
56 [markup.goldmark.parser.attribute]
57 block = true
58 {{< /code-toggle >}}
59
60 Hugo populates the `Attributes` map for _block_ passthrough elements. Markdown attributes are not applicable to _inline_ elements.
61
62 Inner
63 : (`string`) The inner content of the passthrough element, excluding the delimiters.
64
65 Ordinal
66 : (`int`) The zero-based ordinal of the passthrough element on the page.
67
68 Page
69 : (`page`) A reference to the current page.
70
71 PageInner
72 : (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
73
74 Position
75 : (`string`) The position of the passthrough element within the page content.
76
77 Type
78 : (`string`) The passthrough element type, either `block` or `inline`.
79
80 [Markdown attributes]: /content-management/markdown-attributes/
81 [`RenderShortcodes`]: /methods/page/rendershortcodes
82
83 ## Example
84
85 Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, create a passthrough render hook which calls the [`transform.ToMath`] function.
86
87 [`transform.ToMath`]: /functions/transform/tomath/
88
89 ```go-html-template {file="layouts/_markup/render-passthrough.html" copy=true}
90 {{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
91 {{- with try (transform.ToMath .Inner $opts) }}
92 {{- with .Err }}
93 {{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
94 {{- else }}
95 {{- .Value }}
96 {{- $.Page.Store.Set "hasMath" true }}
97 {{- end }}
98 {{- end -}}
99 ```
100
101 Then, in your base template, conditionally include the KaTeX CSS within the head element:
102
103 ```go-html-template {file="layouts/baseof.html" copy=true}
104 <head>
105 {{ $noop := .WordCount }}
106 {{ if .Page.Store.Get "hasMath" }}
107 <link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
108 {{ end }}
109 </head>
110 ```
111
112 In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
113
114 Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of passthrough element:
115
116 ```text
117 layouts/
118 └── _markup/
119 ├── render-passthrough-block.html
120 └── render-passthrough-inline.html
121 ```
122
123 {{% include "/_common/render-hooks/pageinner.md" %}}