diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index 2fb13ad36..b323ba464 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -119,161 +119,5 @@ ordered ## Markdown Render Hooks -{{< new-in "0.62.0" >}} +See [Markdown Render Hooks](/templates/render-hooks/). -Note that this is only supported with the [Goldmark](#goldmark) renderer. - -Render Hooks allow custom templates to override markdown rendering functionality. You can do this by creating templates with base names `render-{feature}` in `layouts/_default/_markup`. - -You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.{{< new-in "0.71.0" >}} - -The features currently supported are: - -* `image` -* `link` -* `heading` {{< new-in "0.71.0" >}} -* `code blocks`{{< new-in "0.83.0" >}} - -You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this: - -```bash -layouts -└── _default - └── _markup - ├── render-image.html - ├── render-image.rss.xml - └── render-link.html - └── render-codeblock.html - └── render-codeblock-bash.html -``` - -Some use cases for the above: - -* 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. -* Add `target=_blank` to external links. -* Resolve and [process](/content-management/image-processing/) images. -* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts). - -### Render Hook Templates - -The `render-link` and `render-image` templates will receive this context: - -Page -: The [Page](/variables/page/) being rendered. - -Destination -: The URL. - -Title -: The title attribute. - -Text -: The rendered (HTML) link text. - -PlainText -: The plain variant of the above. - -The `render-heading` template will receive this context: - -Page -: The [Page](/variables/page/) being rendered. - -Level -: The header level (1--6) - -Anchor -: An auto-generated html id unique to the header within the page - -Text -: The rendered (HTML) text. - -PlainText -: The plain variant of the above. - -Attributes (map) {{< new-in "0.82.0" >}} -: A map of attributes (e.g. `id`, `class`) - -#### Link with title Markdown example: - -```md -[Text](https://www.gohugo.io "Title") -``` - -Here is a code example for how the render-link.html template could look: - -{{< code file="layouts/_default/_markup/render-link.html" >}} -{{ .Text | safeHTML }} -{{< /code >}} - -#### Image Markdown example: - -```md -![Text](https://d33wubrfki0l68.cloudfront.net/c38c7334cc3f23585738e40334284fddcaf03d5e/2e17c/images/hugo-logo-wide.svg "Title") -``` - -Here is a code example for how the render-image.html template could look: - -{{< code file="layouts/_default/_markup/render-image.html" >}} -

- {{ .Text }} -

-{{< /code >}} - -#### Heading link example - -Given this template file - -{{< code file="layouts/_default/_markup/render-heading.html" >}} -{{ .Text | safeHTML }} -{{< /code >}} - -And this markdown - -```md -### Section A -``` - -The rendered html will be - -```html -

Section A

-``` - -## Render Hooks for Code Blocks - -{{< new-in "0.93.0" >}} - -You can add a hook template for either all code blocks or for a specific type/language (`bash` in the example below): - -```bash -layouts -└── _default - └── _markup - └── render-codeblock.html - └── render-codeblock-bash.html -``` - -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. - -The context (the ".") you receive in a code block template contains: - -Type (string) -: The type of code block. This will be the programming language, e.g. `bash`, when doing code highlighting. - -Attributes (map) -: Attributes passed in from Markdown (e.g. `{ attrName1=attrValue1 attrName2="attr Value 2" }`). - -Options (map) -: 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). - -Inner (string) -: The text between the code fences. - -Ordinal (string) -: Zero-based ordinal for all code blocks in the current document. - -Page -: The owning `Page`. - -Position -: Useful in error logging as it prints the filename and position (linenumber, column), e.g. `{{ errorf "error in code block: %s" .Position }}`. diff --git a/content/en/templates/render-hooks.md b/content/en/templates/render-hooks.md new file mode 100644 index 000000000..44ab4187b --- /dev/null +++ b/content/en/templates/render-hooks.md @@ -0,0 +1,175 @@ +--- +title: "Markdown Render Hooks" +linkTitle: "Render Hooks" +description: "Render Hooks allow custom templates to override markdown rendering functionality." +date: 2017-03-11 +categories: [templates] +keywords: [markdown] +toc: true +menu: + docs: + title: "Markdown Render Hooks" + parent: "templates" + weight: 20 +--- + + + + +{{< new-in "0.62.0" >}} Note that this is only supported with the [Goldmark](#goldmark) renderer. + + +You can override certain parts of the default Markdown rendering to HTML by creating templates with base names `render-{kind}` in `layouts/_default/_markup`. + +You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.{{< new-in "0.71.0" >}} + +The hook kinds currently supported are: + +* `image` +* `link` +* `heading` {{< new-in "0.71.0" >}} +* `codeblock`{{< new-in "0.83.0" >}} + +You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this: + +```bash +layouts +└── _default + └── _markup + ├── render-image.html + ├── render-image.rss.xml + └── render-link.html + └── render-codeblock.html + └── render-codeblock-bash.html +``` + +Some use cases for the above: + +* 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. +* Add `target=_blank` to external links. +* Resolve and [process](/content-management/image-processing/) images. +* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts). + +## Render Hooks for Headings, Links and Images + +The `render-link` and `render-image` templates will receive this context: + +Page +: The [Page](/variables/page/) being rendered. + +Destination +: The URL. + +Title +: The title attribute. + +Text +: The rendered (HTML) link text. + +PlainText +: The plain variant of the above. + +The `render-heading` template will receive this context: + +Page +: The [Page](/variables/page/) being rendered. + +Level +: The header level (1--6) + +Anchor +: An auto-generated html id unique to the header within the page + +Text +: The rendered (HTML) text. + +PlainText +: The plain variant of the above. + +Attributes (map) {{< new-in "0.82.0" >}} +: A map of attributes (e.g. `id`, `class`) + +### Link with title Markdown example: + +```md +[Text](https://www.gohugo.io "Title") +``` + +Here is a code example for how the render-link.html template could look: + +{{< code file="layouts/_default/_markup/render-link.html" >}} +{{ .Text | safeHTML }} +{{< /code >}} + +### Image Markdown example: + +```md +![Text](https://d33wubrfki0l68.cloudfront.net/c38c7334cc3f23585738e40334284fddcaf03d5e/2e17c/images/hugo-logo-wide.svg "Title") +``` + +Here is a code example for how the render-image.html template could look: + +{{< code file="layouts/_default/_markup/render-image.html" >}} +

+ {{ .Text }} +

+{{< /code >}} + +### Heading link example + +Given this template file + +{{< code file="layouts/_default/_markup/render-heading.html" >}} +{{ .Text | safeHTML }} +{{< /code >}} + +And this markdown + +```md +### Section A +``` + +The rendered html will be + +```html +

Section A

+``` + +## Render Hooks for Code Blocks + +{{< new-in "0.93.0" >}} + +You can add a hook template for either all code blocks or for a specific type/language (`bash` in the example below): + +```bash +layouts +└── _default + └── _markup + └── render-codeblock.html + └── render-codeblock-bash.html +``` + +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. + +The context (the ".") you receive in a code block template contains: + +Type (string) +: The type of code block. This will be the programming language, e.g. `bash`, when doing code highlighting. + +Attributes (map) +: Attributes passed in from Markdown (e.g. `{ attrName1=attrValue1 attrName2="attr Value 2" }`). + +Options (map) +: 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). + +Inner (string) +: The text between the code fences. + +Ordinal (string) +: Zero-based ordinal for all code blocks in the current document. + +Page +: The owning `Page`. + +Position +: Useful in error logging as it prints the filename and position (linenumber, column), e.g. `{{ errorf "error in code block: %s" .Position }}`.