mirror/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2025-08-28 22:19:59 +02:00
Code Issues Packages Projects Releases Wiki Activity

Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'

Browse Source
This commit is contained in:
Bjørn Erik Pedersen
2025-04-10 13:04:51 +02:00
parent 208a0de6c3 5be51ac3db
commit 653f1c1d46
987 changed files with 12379 additions and 14083 deletions
Download Patch File Download Diff File Expand all files Collapse all files

93
docs/content/en/render-hooks/passthrough.md
View File

@@ -1,29 +1,23 @@
---
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]
description: Create a passthrough render hook to override the rendering of text snippets captured by the Goldmark Passthrough extension.
categories: []
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_.
Hugo uses [Goldmark] to render Markdown to HTML. Goldmark supports custom extensions to extend its core functionality. The [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
[Passthrough]: /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 >}}
```text {file="content/example.md"}
This is a
\[block\]
@@ -31,9 +25,9 @@ This is a
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:
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]
@@ -45,7 +39,7 @@ inline = [['\(', '\)']]
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 the LaTeX markup language.
The Passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in the LaTeX markup language.
[mathematical expressions]: /content-management/mathematics/
@@ -55,72 +49,65 @@ To enable custom rendering of passthrough elements, create a passthrough render
Passthrough render hook templates receive the following [context](g):
###### Attributes
Attributes
: (`map`) The [Markdown attributes], available if you configure your site as follows:
(`map`) The [Markdown attributes], available if you configure your site as follows:
{{< 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).
Position
: (`string`) The position of the passthrough element within the page content.
Type
: (`string`) The passthrough element type, either `block` or `inline`.
[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
(`string`) The passthrough element type, either `block` or `inline`.
## Example
Instead of client-side JavaScript rendering of mathematical markup using MathJax or KaTeX, 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 >}}
```go-html-template {file="layouts/_default/_markup/render-passthrough.html" copy=true}
{{- $opts := dict "output" "htmlAndMathml" "displayMode" (eq .Type "block") }}
{{- with try (transform.ToMath .Inner $opts) }}
{{- with .Err }}
{{ errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
{{- errorf "Unable to render mathematical markup to HTML using the transform.ToMath function. The KaTeX display engine threw the following error: %s: see %s." . $.Position }}
{{- else }}
{{- .Value }}
{{- $.Page.Store.Set "hasMath" true }}
{{- end }}
{{- end -}}
{{< /code >}}
```
Then, in your base template, conditionally include the KaTeX CSS within the head element:
{{< code file=layouts/_default/baseof.html copy=true >}}
```go-html-template {file="layouts/_default/baseof.html" copy=true}
<head>
{{ $noop := .WordCount }}
{{ if .Page.Store.Get "hasMath" }}
<link href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css" rel="stylesheet">
{{ end }}
</head>
{{< /code >}}
```
In the above, note the use of a [noop](g) statement to force content rendering before we check the value of `hasMath` with the `Store.Get` method.
@@ -134,4 +121,4 @@ layouts/
└── render-passthrough-inline.html
```
{{% include "/render-hooks/_common/pageinner.md" %}}
{{% include "/_common/render-hooks/pageinner.md" %}}