render-hooks.md (5381B)
1 ---
2 title: "Markdown Render Hooks"
3 linkTitle: "Render Hooks"
4 description: "Render Hooks allow custom templates to override markdown rendering functionality."
5 date: 2017-03-11
6 categories: [templates]
7 keywords: [markdown]
8 toc: true
9 menu:
10 docs:
11 title: "Markdown Render Hooks"
12 parent: "templates"
13 weight: 20
14 ---
15
16 {{< new-in "0.62.0" >}} Note that this is only supported with the [Goldmark](/getting-started/configuration-markup#goldmark) renderer.
17
18
19 You can override certain parts of the default Markdown rendering to HTML by creating templates with base names `render-{kind}` in `layouts/_default/_markup`.
20
21 You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.{{< new-in "0.71.0" >}}
22
23 The hook kinds currently supported are:
24
25 * `image`
26 * `link`
27 * `heading` {{< new-in "0.71.0" >}}
28 * `codeblock`{{< new-in "0.93.0" >}}
29
30 You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this:
31
32 ```goat { class="black f7" }
33 layouts
34 └── _default
35 └── _markup
36 ├── render-image.html
37 ├── render-image.rss.xml
38 └── render-link.html
39 └── render-codeblock.html
40 └── render-codeblock-bash.html
41 ```
42
43 Some use cases for the above:
44
45 * Resolve link references using `.GetPage`. This would make links portable as you could translate `./my-post.md` (and similar constructs that would work on GitHub) into `/blog/2019/01/01/my-post/` etc.
46 * Add `target=_blank` to external links.
47 * Resolve and [process](/content-management/image-processing/) images.
48 * Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts).
49
50 ## Render Hooks for Headings, Links and Images
51
52 The `render-link` and `render-image` templates will receive this context:
53
54 Page
55 : The [Page](/variables/page/) being rendered.
56
57 Destination
58 : The URL.
59
60 Title
61 : The title attribute.
62
63 Text
64 : The rendered (HTML) link text.
65
66 PlainText
67 : The plain variant of the above.
68
69 The `render-heading` template will receive this context:
70
71 Page
72 : The [Page](/variables/page/) being rendered.
73
74 Level
75 : The header level (1--6)
76
77 Anchor
78 : An auto-generated html id unique to the header within the page
79
80 Text
81 : The rendered (HTML) text.
82
83 PlainText
84 : The plain variant of the above.
85
86 Attributes (map) {{< new-in "0.82.0" >}}
87 : A map of attributes (e.g. `id`, `class`)
88
89 ### Link with title Markdown example:
90
91 ```md
92 [Text](https://www.gohugo.io "Title")
93 ```
94
95 Here is a code example for how the render-link.html template could look:
96
97 {{< code file="layouts/_default/_markup/render-link.html" >}}
98 <a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>
99 {{< /code >}}
100
101 ### Image Markdown example:
102
103 ```md
104 
105 ```
106
107 Here is a code example for how the render-image.html template could look:
108
109 {{< code file="layouts/_default/_markup/render-image.html" >}}
110 <p class="md__image">
111 <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
112 </p>
113 {{< /code >}}
114
115 ### Heading link example
116
117 Given this template file
118
119 {{< code file="layouts/_default/_markup/render-heading.html" >}}
120 <h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>
121 {{< /code >}}
122
123 And this markdown
124
125 ```md
126 ### Section A
127 ```
128
129 The rendered html will be
130
131 ```html
132 <h3 id="section-a">Section A <a href="#section-a">¶</a></h3>
133 ```
134
135 ## Render Hooks for Code Blocks
136
137 {{< new-in "0.93.0" >}}
138
139 You can add a hook template for either all code blocks or for a specific type/language (`bash` in the example below):
140
141 ```goat { class="black f7" }
142 layouts
143 └── _default
144 └── _markup
145 └── render-codeblock.html
146 └── render-codeblock-bash.html
147 ```
148
149 The default behaviour for these code blocks is to do [Code Highlighting](/content-management/syntax-highlighting/#highlighting-in-code-fences), but since you can pass attributes to these code blocks, they can be used for almost anything. One example would be the built-in [GoAT Diagrams](/content-management/diagrams/#goat-diagrams-ascii) or this [Mermaid Diagram Code Block Hook](/content-management/diagrams/#mermaid-diagrams) example.
150
151 The context (the ".") you receive in a code block template contains:
152
153 Type (string)
154 : The type of code block. This will be the programming language, e.g. `bash`, when doing code highlighting.
155
156 Attributes (map)
157 : Attributes passed in from Markdown (e.g. `{ attrName1=attrValue1 attrName2="attr Value 2" }`).
158
159 Options (map)
160 : Chroma highlighting processing options. This will only be filled if `Type` is a known [Chroma Lexer](/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages).
161
162 Inner (string)
163 : The text between the code fences.
164
165 Ordinal (integer)
166 : Zero-based ordinal for all code blocks in the current document.
167
168 Page
169 : The owning `Page`.
170
171 Position
172 : Useful in error logging as it prints the filename and position (linenumber, column), e.g. `{{ errorf "error in code block: %s" .Position }}`.