mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
dec8cd4ada
a49697e53 Add private use subtag requirements to multilingual page a5c6bb4da Add INFINI Pizza search engine 45b732efa Fix template lookup order for AMP pages 30c672d0b netlify: Hugo 0.133.1 7c766e724 Update page resources documentation ca802fbec Document how to enable AsciiDoc syntax highlighting c3350f4cf Update definition of falsy to include zero time.Time values b0e5ab051 Fir typo 60f6cb63b Update migrations.md ec52c7ba1 Improve formatting of example code e5681ad01 Improve formatting of example code bdf3ffc73 Clarify the various next/prev methods b5505d22a Clarify template lookup order for shortcodes cf8dd7034 Improve embedded.md e5dee2651 Update transform.ToMath 4d419a128 Update pagination configuration to use new struct 05d4fd597 Update PrevInSection.md fd33370ed Add new-in 0.133.0 f9062042f Add the new page config section 205645e97 Remove out-dated new-in 3ed3673f7 Fix typo 41df91659 Document the 'else with' construct introduced with Go 1.23 9c4697ab3 netlify: Hugo 0.133.0 62506b052 Merge branch 'temp133' 877e1bfcd Add config options page.nextPrevSortOrder/nextPrevInSectionSortOrder eb159fe62 Update menu.md efa7795a0 Update theme dbe8911ad netlify: Hugo 0.132.2 2f793d328 Document passthrough render hooks a7ce9a5e8 netlify: Hugo 0.132.1 2c137cb48 Update blockquotes.md e0fa2f0d1 Add new-in badge to blockquote render hook page bf42bbe6b Update references to render hooks 85a3d9958 Update theme 2dae72128 Document blockquote render hooks 8f5afb55d Update plainify return type 160f22d0e netlify: Hugo 0.132.0 82b5586fb Document transform.ToMath 1efcbcddb tpl/transform: Make Plainify and ToMath return template.HTML 31727be2e docs: Regen docshelper 88a421426 Merge commit 'a6e635ca7d905d9ec3ffd708db2694f680b03aae' git-subtree-dir: docs git-subtree-split: a49697e536ee0d477ab4e552cfa8dc74debeff27
125 lines
4 KiB
Markdown
Executable file
125 lines
4 KiB
Markdown
Executable file
---
|
|
title: Passthrough render hooks
|
|
linkTitle: Passthrough
|
|
description: Create a passthrough render hook to override the rendering of text snippets captured by the Goldmark passthrough extension.
|
|
categories: [render hooks]
|
|
keywords: []
|
|
menu:
|
|
docs:
|
|
parent: render-hooks
|
|
weight: 80
|
|
weight: 80
|
|
toc: true
|
|
---
|
|
|
|
{{< new-in 0.132.0 >}}
|
|
|
|
## Overview
|
|
|
|
Hugo uses [Goldmark] to render Markdown to HTML. Goldmark supports custom extensions to extend its core functionality. The Goldmark [passthrough extension] captures and preserves raw Markdown within delimited snippets of text, including the delimiters themselves. These are known as _passthrough elements_.
|
|
|
|
[Goldmark]: https://github.com/yuin/goldmark
|
|
[passthrough extension]: /getting-started/configuration-markup/#passthrough
|
|
|
|
Depending on your choice of delimiters, Hugo will classify a passthrough element as either _block_ or _inline_. Consider this contrived example:
|
|
|
|
{{< code file=content/sample.md >}}
|
|
This is a
|
|
|
|
\[block\]
|
|
|
|
passthrough element with opening and closing block delimiters.
|
|
|
|
This is an \(inline\) passthrough element with opening and closing inline delimiters.
|
|
{{< /code >}}
|
|
|
|
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:
|
|
|
|
{{< code-toggle file=hugo >}}
|
|
[markup.goldmark.extensions.passthrough]
|
|
enable = true
|
|
[markup.goldmark.extensions.passthrough.delimiters]
|
|
block = [['\[', '\]'], ['$$', '$$']]
|
|
inline = [['\(', '\)']]
|
|
{{< /code-toggle >}}
|
|
|
|
In the example above there are two sets of `block` delimiters. You may use either one in your Markdown.
|
|
|
|
The Goldmark passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in [LaTeX] or [Tex].
|
|
|
|
[mathematical expressions]: /content-management/mathematics/
|
|
[LaTeX]: https://www.latex-project.org/
|
|
[Tex]: https://en.wikipedia.org/wiki/TeX
|
|
|
|
To enable custom rendering of passthrough elements, create a render hook.
|
|
|
|
## Context
|
|
|
|
Passthrough render hook templates receive the following [context]:
|
|
|
|
[context]: /getting-started/glossary/#context
|
|
|
|
###### Attributes
|
|
|
|
(`map`) The [Markdown attributes], available if you configure your site as follows:
|
|
|
|
[Markdown attributes]: /content-management/markdown-attributes/
|
|
|
|
{{< code-toggle file=hugo >}}
|
|
[markup.goldmark.parser.attribute]
|
|
block = true
|
|
{{< /code-toggle >}}
|
|
|
|
Hugo populates the `Attributes` map for _block_ passthrough elements. Markdown attributes are not applicable to _inline_ elements.
|
|
|
|
###### Inner
|
|
(`string`) The inner content of the passthrough element, excluding the delimiters.
|
|
|
|
###### Ordinal
|
|
|
|
(`int`) The zero-based ordinal of the passthrough element on the page.
|
|
|
|
###### Page
|
|
|
|
(`page`) A reference to the current page.
|
|
|
|
###### PageInner
|
|
|
|
(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
|
|
|
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
|
|
|
###### Position
|
|
|
|
(`string`) The position of the passthrough element within the page content.
|
|
|
|
###### Type
|
|
|
|
(`bool`) The passthrough element type, either `block` or `inline`.
|
|
|
|
## Example
|
|
|
|
As an alternative to rendering mathematical expressions with the MathJax or KaTeX display engine, create a passthrough render hook which calls the [`transform.ToMath`] function:
|
|
|
|
[`transform.ToMath`]: /functions/transform/tomath/
|
|
|
|
{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}}
|
|
{{ if eq .Type "block" }}
|
|
{{ $opts := dict "displayMode" true }}
|
|
{{ transform.ToMath .Inner $opts }}
|
|
{{ else }}
|
|
{{ transform.ToMath .Inner }}
|
|
{{ end }}
|
|
{{< /code >}}
|
|
|
|
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:
|
|
|
|
```text
|
|
layouts/
|
|
└── _default/
|
|
└── _markup/
|
|
├── render-passthrough-block.html
|
|
└── render-passthrough-inline.html
|
|
```
|
|
|
|
{{% include "/render-hooks/_common/pageinner.md" %}}
|