diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md index 8ae2f4d33b..73c36dd4c2 100644 --- a/content/en/functions/transform/ToMath.md +++ b/content/en/functions/transform/ToMath.md @@ -112,6 +112,3 @@ There are 3 ways to handle errors from KaTeX: [options]: #options [error handling]: #error-handling [KaTeX options]: https://katex.org/docs/options.html - - - diff --git a/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md index 103d9a84ea..3745fc398d 100755 --- a/content/en/render-hooks/introduction.md +++ b/content/en/render-hooks/introduction.md @@ -18,6 +18,7 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend - [Headings](/render-hooks/headings) - [Images](/render-hooks/images) - [Links](/render-hooks/links) +- [Passthrough elements](/render-hooks/passthrough) {{% note %}} Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText. diff --git a/content/en/render-hooks/passthrough.md b/content/en/render-hooks/passthrough.md new file mode 100755 index 0000000000..3b82116e6a --- /dev/null +++ b/content/en/render-hooks/passthrough.md @@ -0,0 +1,125 @@ +--- +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" %}}