mirror of
https://github.com/gohugoio/hugo.git
synced 2025-08-17 21:01:26 +02:00
Merge commit '5be51ac3db225d5df501ed1fa1499c41d97dbf65'
This commit is contained in:
Bjørn Erik Pedersen
@@ -1,13 +0,0 @@
|
||||
---
|
||||
cascade:
|
||||
_build:
|
||||
list: never
|
||||
publishResources: false
|
||||
render: never
|
||||
---
|
||||
|
||||
<!--
|
||||
Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
|
||||
|
||||
Include the rendered content using the "include" shortcode.
|
||||
-->
|
||||
@@ -1,47 +0,0 @@
|
||||
---
|
||||
_comment: Do not remove front matter.
|
||||
---
|
||||
|
||||
## PageInner details
|
||||
|
||||
{{< new-in 0.125.0 />}}
|
||||
|
||||
The primary use case for `PageInner` is to resolve links and [page resources](g) relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
|
||||
|
||||
{{< code file=layouts/shortcodes/include.html >}}
|
||||
{{ with .Get 0 }}
|
||||
{{ with $.Page.GetPage . }}
|
||||
{{- .RenderShortcodes }}
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode was unable to find %q. See %s" $.Name . $.Position }}
|
||||
{{ end }}
|
||||
{{ else }}
|
||||
{{ errorf "The %q shortcode requires a positional parameter indicating the logical path of the file to include. See %s" .Name .Position }}
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
|
||||
Then call the shortcode in your Markdown:
|
||||
|
||||
{{< code file=content/posts/p1.md >}}
|
||||
{{%/* include "/posts/p2" */%}}
|
||||
{{< /code >}}
|
||||
|
||||
Any render hook triggered while rendering `/posts/p2` will get:
|
||||
|
||||
- `/posts/p1` when calling `Page`
|
||||
- `/posts/p2` when calling `PageInner`
|
||||
|
||||
`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
|
||||
|
||||
{{% note %}}
|
||||
The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using the `{{%/*..*/%}}` notation.
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes/
|
||||
{{% /note %}}
|
||||
|
||||
As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each:
|
||||
|
||||
- [Embedded link render hook]({{% eturl render-link %}})
|
||||
- [Embedded image render hook]({{% eturl render-image %}})
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes/
|
||||
@@ -1,17 +1,8 @@
|
||||
---
|
||||
title: Render hooks
|
||||
|
||||
description: Create render hooks to override the rendering of Markdown to HTML.
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: render-hooks-in-this-section
|
||||
parent: render-hooks
|
||||
weight: 10
|
||||
weight: 10
|
||||
showSectionMenu: false
|
||||
aliases: [/templates/render-hooks/]
|
||||
---
|
||||
|
||||
Create render hooks to override the rendering of Markdown to HTML.
|
||||
|
||||
@@ -2,14 +2,8 @@
|
||||
title: Blockquote render hooks
|
||||
linkTitle: Blockquotes
|
||||
description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML.
|
||||
categories: [render hooks]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: render-hooks
|
||||
weight: 30
|
||||
weight: 30
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.132.0 />}}
|
||||
@@ -18,73 +12,56 @@ toc: true
|
||||
|
||||
Blockquote render hook templates receive the following [context](g):
|
||||
|
||||
###### AlertType
|
||||
AlertType
|
||||
: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below.
|
||||
|
||||
(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below.
|
||||
AlertTitle
|
||||
: {{< new-in 0.134.0 />}}
|
||||
: (`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below.
|
||||
|
||||
###### AlertTitle
|
||||
AlertSign
|
||||
: {{< new-in 0.134.0 />}}
|
||||
: (`string`) Applicable when [`Type`](#type) is `alert`, this is the alert sign. Typically used to indicate whether an alert is graphically foldable, this is one of `+`, `-`, or an empty string. See the [alerts](#alerts) section below.
|
||||
|
||||
{{< new-in 0.134.0 />}}
|
||||
Attributes
|
||||
: (`map`) The [Markdown attributes], available if you configure your site as follows:
|
||||
|
||||
(`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below.
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser.attribute]
|
||||
block = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
###### AlertSign
|
||||
Ordinal
|
||||
: (`int`) The zero-based ordinal of the blockquote on the page.
|
||||
|
||||
{{< new-in 0.134.0 />}}
|
||||
Page
|
||||
: (`page`) A reference to the current page.
|
||||
|
||||
(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert sign. Typically used to indicate whether an alert is graphically foldable, this is one of `+`, `-`, or an empty string. See the [alerts](#alerts) section below.
|
||||
PageInner
|
||||
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
###### Attributes
|
||||
Position
|
||||
: (`string`) The position of the blockquote within the page content.
|
||||
|
||||
(`map`) The [Markdown attributes], available if you configure your site as follows:
|
||||
Text
|
||||
: (`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below.
|
||||
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser.attribute]
|
||||
block = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
###### Ordinal
|
||||
|
||||
(`int`) The zero-based ordinal of the blockquote 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 blockquote within the page content.
|
||||
|
||||
###### Text
|
||||
(`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below.
|
||||
|
||||
###### Type
|
||||
|
||||
(`bool`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below.
|
||||
Type
|
||||
: (`string`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below.
|
||||
|
||||
## Examples
|
||||
|
||||
In its default configuration, Hugo renders Markdown blockquotes according to the [CommonMark specification]. To create a render hook that does the same thing:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
|
||||
<blockquote>
|
||||
{{ .Text }}
|
||||
</blockquote>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
To render a blockquote as an HTML `figure` element with an optional citation and caption:
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
|
||||
<figure>
|
||||
<blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}>
|
||||
{{ .Text }}
|
||||
@@ -95,7 +72,7 @@ To render a blockquote as an HTML `figure` element with an optional citation and
|
||||
</figcaption>
|
||||
{{ end }}
|
||||
</figure>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Then in your markdown:
|
||||
|
||||
@@ -112,7 +89,7 @@ Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphas
|
||||
|
||||
With the basic Markdown syntax, the first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets. For example:
|
||||
|
||||
{{< code file=content/example.md lang=text >}}
|
||||
```text {file="content/example.md"}
|
||||
> [!NOTE]
|
||||
> Useful information that users should know, even when skimming content.
|
||||
|
||||
@@ -127,34 +104,29 @@ With the basic Markdown syntax, the first line of each alert is an alert designa
|
||||
|
||||
> [!CAUTION]
|
||||
> Advises about risks or negative outcomes of certain actions.
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
The basic syntax is compatible with [GitHub], [Obsidian], and [Typora].
|
||||
|
||||
[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
|
||||
[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts
|
||||
[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts
|
||||
|
||||
### Extended syntax
|
||||
|
||||
With the extended Markdown syntax, you may optionally include an alert sign and/or an alert title. The alert sign is one of `+` or `-`, typically used to indicate whether an alert is graphically foldable. For example:
|
||||
|
||||
{{< code file=content/example.md lang=text >}}
|
||||
```text {file="content/example.md"}
|
||||
> [!WARNING]+ Radiation hazard
|
||||
> Do not approach or handle without protective gear.
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
The extended syntax is compatible with [Obsidian].
|
||||
|
||||
{{% note %}}
|
||||
The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote.
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> The extended syntax is not compatible with GitHub or Typora. If you include an alert sign or an alert title, these applications render the Markdown as a blockquote.
|
||||
|
||||
### Example
|
||||
|
||||
This blockquote render hook renders a multilingual alert if an alert designator is present, otherwise it renders a blockquote according to the CommonMark specification.
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true}
|
||||
{{ $emojis := dict
|
||||
"caution" ":exclamation:"
|
||||
"important" ":information_source:"
|
||||
@@ -180,7 +152,7 @@ This blockquote render hook renders a multilingual alert if an alert designator
|
||||
{{ .Text }}
|
||||
</blockquote>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
To override the label, create these entries in your i18n files:
|
||||
|
||||
@@ -202,4 +174,11 @@ layouts/
|
||||
└── render-blockquote-regular.html
|
||||
```
|
||||
|
||||
{{% include "/render-hooks/_common/pageinner.md" %}}
|
||||
{{% include "/_common/render-hooks/pageinner.md" %}}
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
[GitHub]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
[Obsidian]: https://help.obsidian.md/Editing+and+formatting/Callouts
|
||||
[Typora]: https://support.typora.io/Markdown-Reference/#callouts--github-style-alerts
|
||||
|
||||
@@ -2,27 +2,21 @@
|
||||
title: Code block render hooks
|
||||
linkTitle: Code blocks
|
||||
description: Create a code block render hook to override the rendering of Markdown code blocks to HTML.
|
||||
categories: [render hooks]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: render-hooks
|
||||
weight: 40
|
||||
weight: 40
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Markdown
|
||||
|
||||
This Markdown example contains a fenced code block:
|
||||
|
||||
{{< code file=content/example.md lang=text >}}
|
||||
````text {file="content/example.md"}
|
||||
```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2}
|
||||
declare a=1
|
||||
echo "$a"
|
||||
exit
|
||||
```
|
||||
{{< /code >}}
|
||||
````
|
||||
|
||||
A fenced code block consists of:
|
||||
|
||||
@@ -31,9 +25,6 @@ A fenced code block consists of:
|
||||
- A code sample
|
||||
- A trailing code fence
|
||||
|
||||
[code fence]: https://spec.commonmark.org/0.31.2/#code-fence
|
||||
[info string]: https://spec.commonmark.org/0.31.2/#info-string
|
||||
|
||||
In the previous example, the info string contains:
|
||||
|
||||
- The language of the code sample (the first word)
|
||||
@@ -45,63 +36,46 @@ In the example above, the _generic attributes_ are `class` and `id`. In the abse
|
||||
|
||||
In the example above, the _highlighting options_ are `lineNos` and `tabWidth`. Hugo uses the [Chroma] syntax highlighter to render the code sample. You can control the appearance of the rendered code by specifying one or more [highlighting options].
|
||||
|
||||
[Chroma]: https://github.com/alecthomas/chroma/
|
||||
[highlighting options]: /functions/transform/highlight/#options
|
||||
|
||||
{{% note %}}
|
||||
Although `style` is a global HTML attribute, when used in an info string it is a highlighting option.
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> Although `style` is a global HTML attribute, when used in an info string it is a highlighting option.
|
||||
|
||||
## Context
|
||||
|
||||
Code block render hook templates receive the following [context](g):
|
||||
|
||||
###### Attributes
|
||||
Attributes
|
||||
: (`map`) The generic attributes from the info string.
|
||||
|
||||
(`map`) The generic attributes from the info string.
|
||||
Inner
|
||||
: (`string`) The content between the leading and trailing code fences, excluding the info string.
|
||||
|
||||
###### Inner
|
||||
Options
|
||||
: (`map`) The highlighting options from the info string.
|
||||
|
||||
(`string`) The content between the leading and trailing code fences, excluding the info string.
|
||||
Ordinal
|
||||
: (`int`) The zero-based ordinal of the code block on the page.
|
||||
|
||||
###### Options
|
||||
Page
|
||||
: (`page`) A reference to the current page.
|
||||
|
||||
(`map`) The highlighting options from the info string.
|
||||
PageInner
|
||||
: {{< new-in 0.125.0 />}}
|
||||
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
###### Ordinal
|
||||
Position
|
||||
: (`text.Position`) The position of the code block within the page content.
|
||||
|
||||
(`int`) The zero-based ordinal of the code block on the page.
|
||||
|
||||
###### Page
|
||||
|
||||
(`page`) A reference to the current page.
|
||||
|
||||
###### PageInner
|
||||
|
||||
{{< new-in 0.125.0 />}}
|
||||
|
||||
(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
|
||||
###### Position
|
||||
|
||||
(`text.Position`) The position of the code block within the page content.
|
||||
|
||||
###### Type
|
||||
|
||||
(`string`) The first word of the info string, typically the code language.
|
||||
Type
|
||||
: (`string`) The first word of the info string, typically the code language.
|
||||
|
||||
## Examples
|
||||
|
||||
In its default configuration, Hugo renders fenced code blocks by passing the code sample through the Chroma syntax highlighter and wrapping the result. To create a render hook that does the same thing:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-codeblock.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-codeblock.html" copy=true}
|
||||
{{ $result := transform.HighlightCodeBlock . }}
|
||||
{{ $result.Wrapped }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Although you can use one template with conditional logic to control the behavior on a per-language basis, you can also create language-specific templates.
|
||||
|
||||
@@ -116,35 +90,38 @@ layouts/
|
||||
|
||||
For example, to create a code block render hook to render [Mermaid] diagrams:
|
||||
|
||||
[Mermaid]: https://mermaid.js.org/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-codeblock-mermaid.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-codeblock-mermaid.html" copy=true}
|
||||
<pre class="mermaid">
|
||||
{{- .Inner | htmlEscape | safeHTML }}
|
||||
{{ .Inner | htmlEscape | safeHTML }}
|
||||
</pre>
|
||||
{{ .Page.Store.Set "hasMermaid" true }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Then include this snippet at the bottom of the your base template:
|
||||
Then include this snippet at the _bottom_ of your base template, before the closing `body` tag:
|
||||
|
||||
{{< code file=layouts/_default/baseof.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/baseof.html" copy=true}
|
||||
{{ if .Store.Get "hasMermaid" }}
|
||||
<script type="module">
|
||||
import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs';
|
||||
mermaid.initialize({ startOnLoad: true });
|
||||
</script>
|
||||
{{ end }}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
See the [diagrams] page for details.
|
||||
|
||||
[diagrams]: /content-management/diagrams/#mermaid-diagrams
|
||||
|
||||
## Embedded
|
||||
|
||||
Hugo includes an [embedded code block render hook] to render [GoAT diagrams].
|
||||
|
||||
{{% include "/_common/render-hooks/pageinner.md" %}}
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
[Chroma]: https://github.com/alecthomas/chroma/
|
||||
[code fence]: https://spec.commonmark.org/0.31.2/#code-fence
|
||||
[diagrams]: /content-management/diagrams/#mermaid-diagrams
|
||||
[embedded code block render hook]: {{% eturl render-codeblock-goat %}}
|
||||
[GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
|
||||
|
||||
{{% include "/render-hooks/_common/pageinner.md" %}}
|
||||
[highlighting options]: /functions/transform/highlight/#options
|
||||
[info string]: https://spec.commonmark.org/0.31.2/#info-string
|
||||
[Mermaid]: https://mermaid.js.org/
|
||||
|
||||
@@ -2,78 +2,63 @@
|
||||
title: Heading render hooks
|
||||
linkTitle: Headings
|
||||
description: Create a heading render hook to override the rendering of Markdown headings to HTML.
|
||||
categories: [render hooks]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: render-hooks
|
||||
weight: 50
|
||||
weight: 50
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Context
|
||||
|
||||
Heading render hook templates receive the following [context](g):
|
||||
|
||||
###### Anchor
|
||||
Anchor
|
||||
: (`string`) The `id` attribute of the heading element.
|
||||
|
||||
(`string`) The `id` attribute of the heading element.
|
||||
Attributes
|
||||
: (`map`) The [Markdown attributes], available if you configure your site as follows:
|
||||
|
||||
###### Attributes
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser.attribute]
|
||||
title = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
(`map`) The [Markdown attributes], available if you configure your site as follows:
|
||||
Level
|
||||
: (`int`) The heading level, 1 through 6.
|
||||
|
||||
Page
|
||||
: (`page`) A reference to the current page.
|
||||
|
||||
PageInner
|
||||
: {{< new-in 0.125.0 />}}
|
||||
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
PlainText
|
||||
: (`string`) The heading text as plain text.
|
||||
|
||||
Text
|
||||
: (`template.HTML`) The heading text.
|
||||
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser.attribute]
|
||||
title = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
###### Level
|
||||
|
||||
(`int`) The heading level, 1 through 6.
|
||||
|
||||
###### Page
|
||||
|
||||
(`page`) A reference to the current page.
|
||||
|
||||
###### PageInner
|
||||
|
||||
{{< new-in 0.125.0 />}}
|
||||
|
||||
(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
|
||||
###### PlainText
|
||||
|
||||
(`string`) The heading text as plain text.
|
||||
|
||||
###### Text
|
||||
|
||||
(`template.HTML`) The heading text.
|
||||
|
||||
## Examples
|
||||
|
||||
In its default configuration, Hugo renders Markdown headings according to the [CommonMark specification] with the addition of automatic `id` attributes. To create a render hook that does the same thing:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-heading.html" copy=true}
|
||||
<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
|
||||
{{- .Text -}}
|
||||
</h{{ .Level }}>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
To add an anchor link to the right of each heading:
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-heading.html" copy=true}
|
||||
<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}>
|
||||
{{ .Text }}
|
||||
<a href="#{{ .Anchor }}">#</a>
|
||||
</h{{ .Level }}>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
{{% include "/render-hooks/_common/pageinner.md" %}}
|
||||
{{% include "/_common/render-hooks/pageinner.md" %}}
|
||||
|
||||
@@ -2,14 +2,8 @@
|
||||
title: Image render hooks
|
||||
linkTitle: Images
|
||||
description: Create an image render to hook override the rendering of Markdown images to HTML.
|
||||
categories: [render hooks]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: render-hooks
|
||||
weight: 60
|
||||
weight: 60
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Markdown
|
||||
@@ -28,76 +22,59 @@ These components are passed into the render hook [context](g) as shown below.
|
||||
|
||||
Image render hook templates receive the following context:
|
||||
|
||||
###### 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]
|
||||
wrapStandAloneImageWithinParagraph = false
|
||||
[markup.goldmark.parser.attribute]
|
||||
block = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
Destination
|
||||
: (`string`) The image destination.
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser]
|
||||
wrapStandAloneImageWithinParagraph = false
|
||||
[markup.goldmark.parser.attribute]
|
||||
block = true
|
||||
{{< /code-toggle >}}
|
||||
IsBlock
|
||||
: (`bool`) Reports whether a standalone image is not wrapped within a paragraph element.
|
||||
|
||||
###### Destination
|
||||
Ordinal
|
||||
: (`int`) The zero-based ordinal of the image on the page.
|
||||
|
||||
(`string`) The image destination.
|
||||
Page
|
||||
: (`page`) A reference to the current page.
|
||||
|
||||
###### IsBlock
|
||||
PageInner
|
||||
: {{< new-in 0.125.0 />}}
|
||||
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
(`bool`) Returns true if a standalone image is not wrapped within a paragraph element.
|
||||
PlainText
|
||||
: (`string`) The image description as plain text.
|
||||
|
||||
###### Ordinal
|
||||
Text
|
||||
: (`template.HTML`) The image description.
|
||||
|
||||
(`int`) The zero-based ordinal of the image on the page.
|
||||
|
||||
###### Page
|
||||
|
||||
(`page`) A reference to the current page.
|
||||
|
||||
###### PageInner
|
||||
|
||||
{{< new-in 0.125.0 />}}
|
||||
|
||||
(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
|
||||
###### PlainText
|
||||
|
||||
(`string`) The image description as plain text.
|
||||
|
||||
###### Text
|
||||
|
||||
(`template.HTML`) The image description.
|
||||
|
||||
###### Title
|
||||
|
||||
(`string`) The image title.
|
||||
Title
|
||||
: (`string`) The image title.
|
||||
|
||||
## Examples
|
||||
|
||||
{{% note %}}
|
||||
With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
|
||||
|
||||
In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-image.html" copy=true}
|
||||
<img src="{{ .Destination | safeURL }}"
|
||||
{{- with .PlainText }} alt="{{ . }}"{{ end -}}
|
||||
{{- with .Title }} title="{{ . }}"{{ end -}}
|
||||
>
|
||||
{{- /* chomp trailing newline */ -}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
To render standalone images within `figure` elements:
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-image.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-image.html" copy=true}
|
||||
{{- if .IsBlock -}}
|
||||
<figure>
|
||||
<img src="{{ .Destination | safeURL }}"
|
||||
@@ -111,7 +88,7 @@ To render standalone images within `figure` elements:
|
||||
{{- with .Title }} title="{{ . }}"{{ end -}}
|
||||
>
|
||||
{{- end -}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
Note that the above requires the following site configuration:
|
||||
|
||||
@@ -126,8 +103,6 @@ wrapStandAloneImageWithinParagraph = false
|
||||
|
||||
Hugo includes an [embedded image render hook] to resolve Markdown image destinations. Disabled by default, you can enable it in your site configuration:
|
||||
|
||||
[embedded image render hook]: {{% eturl render-image %}}
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.renderHooks.image]
|
||||
enableDefault = true
|
||||
@@ -135,11 +110,8 @@ enableDefault = true
|
||||
|
||||
A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.
|
||||
|
||||
{{% note %}}
|
||||
The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> The embedded image render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource](g), falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
|
||||
|
||||
@@ -157,4 +129,10 @@ target = 'assets'
|
||||
|
||||
Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.
|
||||
|
||||
{{% include "/render-hooks/_common/pageinner.md" %}}
|
||||
{{% include "/_common/render-hooks/pageinner.md" %}}
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
|
||||
[embedded image render hook]: {{% eturl render-image %}}
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
|
||||
@@ -1,14 +1,9 @@
|
||||
---
|
||||
title: Introduction
|
||||
description: An introduction to Hugo's render hooks.
|
||||
categories: [render hooks]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
identifier: render-hooks-introduction
|
||||
parent: render-hooks
|
||||
weight: 20
|
||||
weight: 20
|
||||
weight: 10
|
||||
---
|
||||
|
||||
When rendering Markdown to HTML, render hooks override the conversion. Each render hook is a template, with one template for each supported element type:
|
||||
@@ -21,13 +16,10 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend
|
||||
- [Passthrough elements](/render-hooks/passthrough)
|
||||
- [Tables](/render-hooks/tables)
|
||||
|
||||
{{% note %}}
|
||||
Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
|
||||
|
||||
The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats.
|
||||
|
||||
[content formats]: /content-management/formats/
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
|
||||
>
|
||||
> The render hook capability is limited to Markdown. You cannot create render hooks for the other content formats.
|
||||
|
||||
For example, consider this Markdown:
|
||||
|
||||
@@ -37,7 +29,7 @@ For example, consider this Markdown:
|
||||
|
||||
```
|
||||
|
||||
Without link or image render hooks, this example above is rendered to:
|
||||
Without link or image render hooks, the example above is rendered to:
|
||||
|
||||
```html
|
||||
<p><a href="https://gohugo.io">Hugo</a></p>
|
||||
@@ -85,3 +77,5 @@ layouts/
|
||||
```
|
||||
|
||||
The remaining pages in this section describe each type of render hook, including examples and the context received by each template.
|
||||
|
||||
[content formats]: /content-management/formats/
|
||||
|
||||
@@ -2,14 +2,8 @@
|
||||
title: Link render hooks
|
||||
linkTitle: Links
|
||||
description: Create a link render hook to override the rendering of Markdown links to HTML.
|
||||
categories: [render hooks]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: render-hooks
|
||||
weight: 70
|
||||
weight: 70
|
||||
toc: true
|
||||
---
|
||||
|
||||
## Markdown
|
||||
@@ -28,56 +22,44 @@ These components are passed into the render hook [context](g) as shown below.
|
||||
|
||||
Link render hook templates receive the following context:
|
||||
|
||||
###### Destination
|
||||
Destination
|
||||
: (`string`) The link destination.
|
||||
|
||||
(`string`) The link destination.
|
||||
Page
|
||||
: (`page`) A reference to the current page.
|
||||
|
||||
###### Page
|
||||
PageInner
|
||||
: {{< new-in 0.125.0 />}}
|
||||
: (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
(`page`) A reference to the current page.
|
||||
PlainText
|
||||
: (`string`) The link description as plain text.
|
||||
|
||||
###### PageInner
|
||||
Text
|
||||
: (`template.HTML`) The link description.
|
||||
|
||||
{{< new-in 0.125.0 />}}
|
||||
|
||||
(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
|
||||
###### PlainText
|
||||
|
||||
(`string`) The link description as plain text.
|
||||
|
||||
###### Text
|
||||
|
||||
(`template.HTML`) The link description.
|
||||
|
||||
###### Title
|
||||
|
||||
(`string`) The link title.
|
||||
Title
|
||||
: (`string`) The link title.
|
||||
|
||||
## Examples
|
||||
|
||||
{{% note %}}
|
||||
With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> With inline elements such as images and links, remove leading and trailing whitespace using the `{{‑ ‑}}` delimiter notation to prevent whitespace between adjacent inline elements and text.
|
||||
|
||||
In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing:
|
||||
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-link.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-link.html" copy=true}
|
||||
<a href="{{ .Destination | safeURL }}"
|
||||
{{- with .Title }} title="{{ . }}"{{ end -}}
|
||||
>
|
||||
{{- with .Text }}{{ . }}{{ end -}}
|
||||
</a>
|
||||
{{- /* chomp trailing newline */ -}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
To include a `rel` attribute set to `external` for external links:
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-link.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-link.html" copy=true}
|
||||
{{- $u := urls.Parse .Destination -}}
|
||||
<a href="{{ .Destination | safeURL }}"
|
||||
{{- with .Title }} title="{{ . }}"{{ end -}}
|
||||
@@ -86,7 +68,7 @@ To include a `rel` attribute set to `external` for external links:
|
||||
{{- with .Text }}{{ . }}{{ end -}}
|
||||
</a>
|
||||
{{- /* chomp trailing newline */ -}}
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
## Default
|
||||
|
||||
@@ -94,8 +76,6 @@ To include a `rel` attribute set to `external` for external links:
|
||||
|
||||
Hugo includes an [embedded link render hook] to resolve Markdown link destinations. Disabled by default, you can enable it in your site configuration:
|
||||
|
||||
[embedded link render hook]: {{% eturl render-link %}}
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.renderHooks.link]
|
||||
enableDefault = true
|
||||
@@ -103,11 +83,8 @@ enableDefault = true
|
||||
|
||||
A custom render hook, even when provided by a theme or module, will override the embedded render hook regardless of the configuration setting above.
|
||||
|
||||
{{% note %}}
|
||||
The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
|
||||
{{% /note %}}
|
||||
> [!note]
|
||||
> The embedded link render hook is automatically enabled for multilingual single-host sites if [duplication of shared page resources] is disabled. This is the default configuration for multilingual single-host sites.
|
||||
|
||||
The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource](g), then falling back to a matching [global resource](g). Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
|
||||
|
||||
@@ -123,4 +100,9 @@ source = 'static'
|
||||
target = 'assets'
|
||||
{{< /code-toggle >}}
|
||||
|
||||
{{% include "/render-hooks/_common/pageinner.md" %}}
|
||||
{{% include "/_common/render-hooks/pageinner.md" %}}
|
||||
|
||||
[`RenderShortcodes`]: /methods/page/rendershortcodes
|
||||
[CommonMark specification]: https://spec.commonmark.org/current/
|
||||
[duplication of shared page resources]: /configuration/markup/#duplicateresourcefiles
|
||||
[embedded link render hook]: {{% eturl render-link %}}
|
||||
|
||||
@@ -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" %}}
|
||||
|
||||
@@ -2,14 +2,8 @@
|
||||
title: Table render hooks
|
||||
linkTitle: Tables
|
||||
description: Create a table render hook to override the rendering of Markdown tables to HTML.
|
||||
categories: [render hooks]
|
||||
categories: []
|
||||
keywords: []
|
||||
menu:
|
||||
docs:
|
||||
parent: render-hooks
|
||||
weight: 90
|
||||
weight: 90
|
||||
toc: true
|
||||
---
|
||||
|
||||
{{< new-in 0.134.0 />}}
|
||||
@@ -18,50 +12,44 @@ toc: true
|
||||
|
||||
Table 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 >}}
|
||||
|
||||
Ordinal
|
||||
: (`int`) The zero-based ordinal of the table 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 table within the page content.
|
||||
|
||||
THead
|
||||
: (`slice`) A slice of table header rows, where each element is a slice of table cells.
|
||||
|
||||
TBody
|
||||
: (`slice`) A slice of table body rows, where each element is a slice of table cells.
|
||||
|
||||
[Markdown attributes]: /content-management/markdown-attributes/
|
||||
|
||||
{{< code-toggle file=hugo >}}
|
||||
[markup.goldmark.parser.attribute]
|
||||
block = true
|
||||
{{< /code-toggle >}}
|
||||
|
||||
###### Ordinal
|
||||
|
||||
(`int`) The zero-based ordinal of the table 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 table within the page content.
|
||||
|
||||
###### THead
|
||||
(`slice`) A slice of table header rows, where each element is a slice of table cells.
|
||||
|
||||
###### TBody
|
||||
(`slice`) A slice of table body rows, where each element is a slice of table cells.
|
||||
|
||||
## Table cells
|
||||
|
||||
Each table cell within the slice of slices returned by the `THead` and `TBody` methods has the following fields:
|
||||
|
||||
###### Alignment
|
||||
(`string`) The alignment of the text within the table cell, one of `left`, `center`, or `right`.
|
||||
Alignment
|
||||
: (`string`) The alignment of the text within the table cell, one of `left`, `center`, or `right`.
|
||||
|
||||
###### Text
|
||||
(`template.HTML`) The text within the table cell.
|
||||
Text
|
||||
: (`template.HTML`) The text within the table cell.
|
||||
|
||||
## Example
|
||||
|
||||
@@ -69,7 +57,7 @@ In its default configuration, Hugo renders Markdown tables according to the [Git
|
||||
|
||||
[GitHub Flavored Markdown specification]: https://github.github.com/gfm/#tables-extension-
|
||||
|
||||
{{< code file=layouts/_default/_markup/render-table.html copy=true >}}
|
||||
```go-html-template {file="layouts/_default/_markup/render-table.html" copy=true}
|
||||
<table
|
||||
{{- range $k, $v := .Attributes }}
|
||||
{{- if $v }}
|
||||
@@ -107,6 +95,6 @@ In its default configuration, Hugo renders Markdown tables according to the [Git
|
||||
{{- end }}
|
||||
</tbody>
|
||||
</table>
|
||||
{{< /code >}}
|
||||
```
|
||||
|
||||
{{% include "/render-hooks/_common/pageinner.md" %}}
|
||||
{{% include "/_common/render-hooks/pageinner.md" %}}
|
||||
|
||||
Reference in New Issue
Block a user