diff options
Diffstat (limited to 'docs/content/en/getting-started')
-rw-r--r-- | docs/content/en/getting-started/configuration-markup.md | 51 |
1 files changed, 46 insertions, 5 deletions
diff --git a/docs/content/en/getting-started/configuration-markup.md b/docs/content/en/getting-started/configuration-markup.md index 337fe00ef..df4449bbf 100644 --- a/docs/content/en/getting-started/configuration-markup.md +++ b/docs/content/en/getting-started/configuration-markup.md @@ -85,9 +85,13 @@ ordered Note that this is only supported with the [Goldmark](#goldmark) renderer. -These Render Hooks allow custom templates to render links and images from markdown. +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 do this by creating templates with base names `render-link` and/or `render-image` inside `layouts/_default/_markup`. +The features currently supported are: + +* `image` +* `link` +* `heading` {{< new-in "0.71.0" >}} You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed.[^hooktemplate] Your `layouts` folder may look like this: @@ -105,10 +109,11 @@ 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 -Both `render-link` and `render-image` templates will receive this context: +The `render-link` and `render-image` templates will receive this context: Page : The [Page](/variables/page/) being rendered. @@ -125,7 +130,24 @@ Text PlainText : The plain variant of the above. -#### Link with title Markdown example : +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. + +#### Link with title Markdown example: ```md [Text](https://www.gohugo.io "Title") @@ -151,5 +173,24 @@ Here is a code example for how the render-image.html template could look: </p> {{< /code >}} -[^hooktemplate]: It's currently only possible to have one set of render hook templates, e.g. not per `Type` or `Section`. We may consider that in a future version. +#### Heading link example + +Given this template file + +{{< code file="layouts/_default/_markup/render-heading.html" >}} +<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}> +{{< /code >}} + +And this markdown + +```md +### Section A +``` + +The rendered html will be +```html +<h3 id="section-a">Section A <a href="#section-a">¶</a></h3> +``` + +[^hooktemplate]: It's currently only possible to have one set of render hook templates, e.g. not per `Type` or `Section`. We may consider that in a future version. |