diff options
Diffstat (limited to 'docs/content/en/render-hooks')
| -rw-r--r-- | docs/content/en/render-hooks/_index.md | 8 | ||||
| -rwxr-xr-x | docs/content/en/render-hooks/blockquotes.md | 184 | ||||
| -rwxr-xr-x | docs/content/en/render-hooks/code-blocks.md | 127 | ||||
| -rwxr-xr-x | docs/content/en/render-hooks/headings.md | 64 | ||||
| -rwxr-xr-x | docs/content/en/render-hooks/images.md | 138 | ||||
| -rwxr-xr-x | docs/content/en/render-hooks/introduction.md | 81 | ||||
| -rwxr-xr-x | docs/content/en/render-hooks/links.md | 108 | ||||
| -rwxr-xr-x | docs/content/en/render-hooks/passthrough.md | 124 | ||||
| -rwxr-xr-x | docs/content/en/render-hooks/tables.md | 100 |
9 files changed, 934 insertions, 0 deletions
diff --git a/docs/content/en/render-hooks/_index.md b/docs/content/en/render-hooks/_index.md new file mode 100644 index 000000000..a5e6203ff --- /dev/null +++ b/docs/content/en/render-hooks/_index.md @@ -0,0 +1,8 @@ +--- +title: Render hooks +description: Create render hooks to override the rendering of Markdown to HTML. +categories: [] +keywords: [] +weight: 10 +aliases: [/templates/render-hooks/] +--- diff --git a/docs/content/en/render-hooks/blockquotes.md b/docs/content/en/render-hooks/blockquotes.md new file mode 100755 index 000000000..7ba282a0a --- /dev/null +++ b/docs/content/en/render-hooks/blockquotes.md @@ -0,0 +1,184 @@ +--- +title: Blockquote render hooks +linkTitle: Blockquotes +description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML. +categories: [] +keywords: [] +--- + +{{< new-in 0.132.0 />}} + +## Context + +Blockquote render hook templates receive the following [context](g): + +AlertType +: (`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. + +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. + +Attributes +: (`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 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). + +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 +: (`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: + +```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true} +<blockquote> + {{ .Text }} +</blockquote> +``` + +To render a blockquote as an HTML `figure` element with an optional citation and caption: + +```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true} +<figure> + <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}> + {{ .Text }} + </blockquote> + {{ with .Attributes.caption }} + <figcaption class="blockquote-caption"> + {{ . | safeHTML }} + </figcaption> + {{ end }} +</figure> +``` + +Then in your markdown: + +```text +> Some text +{cite="https://gohugo.io" caption="Some caption"} +``` + +## Alerts + +Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information. + +### Basic syntax + +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: + +```text {file="content/example.md"} +> [!NOTE] +> Useful information that users should know, even when skimming content. + +> [!TIP] +> Helpful advice for doing things better or more easily. + +> [!IMPORTANT] +> Key information users need to know to achieve their goal. + +> [!WARNING] +> Urgent info that needs immediate user attention to avoid problems. + +> [!CAUTION] +> Advises about risks or negative outcomes of certain actions. +``` + +The basic syntax is compatible with [GitHub], [Obsidian], and [Typora]. + +### 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: + +```text {file="content/example.md"} +> [!WARNING]+ Radiation hazard +> Do not approach or handle without protective gear. +``` + +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. + +### 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. + +```go-html-template {file="layouts/_default/_markup/render-blockquote.html" copy=true} +{{ $emojis := dict + "caution" ":exclamation:" + "important" ":information_source:" + "note" ":information_source:" + "tip" ":bulb:" + "warning" ":information_source:" +}} + +{{ if eq .Type "alert" }} + <blockquote class="alert alert-{{ .AlertType }}"> + <p class="alert-heading"> + {{ transform.Emojify (index $emojis .AlertType) }} + {{ with .AlertTitle }} + {{ . }} + {{ else }} + {{ or (i18n .AlertType) (title .AlertType) }} + {{ end }} + </p> + {{ .Text }} + </blockquote> +{{ else }} + <blockquote> + {{ .Text }} + </blockquote> +{{ end }} +``` + +To override the label, create these entries in your i18n files: + +{{< code-toggle file=i18n/en.toml >}} +caution = 'Caution' +important = 'Important' +note = 'Note' +tip = 'Tip' +warning = 'Warning' +{{< /code-toggle >}} + +Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of blockquote: + +```text +layouts/ +└── _default/ + └── _markup/ + ├── render-blockquote-alert.html + └── render-blockquote-regular.html +``` + +{{% 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 diff --git a/docs/content/en/render-hooks/code-blocks.md b/docs/content/en/render-hooks/code-blocks.md new file mode 100755 index 000000000..d1a01e9b0 --- /dev/null +++ b/docs/content/en/render-hooks/code-blocks.md @@ -0,0 +1,127 @@ +--- +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: [] +keywords: [] +--- + +## Markdown + +This Markdown example contains a fenced code block: + +````text {file="content/example.md"} +```bash {class="my-class" id="my-codeblock" lineNos=inline tabWidth=2} +declare a=1 +echo "$a" +exit +``` +```` + +A fenced code block consists of: + +- A leading [code fence] +- An optional [info string] +- A code sample +- A trailing code fence + +In the previous example, the info string contains: + +- The language of the code sample (the first word) +- An optional space-delimited or comma-delimited list of attributes (everything within braces) + +The attributes in the info string can be generic attributes or highlighting options. + +In the example above, the _generic attributes_ are `class` and `id`. In the absence of special handling within a code block render hook, Hugo adds each generic attribute to the HTML element surrounding the rendered code block. Consistent with its content security model, Hugo removes HTML event attributes such as `onclick` and `onmouseover`. Generic attributes are typically global HTML attributes, but you may include custom attributes as well. + +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]. + +> [!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 +: (`map`) The generic attributes from the info string. + +Inner +: (`string`) The content between the leading and trailing code fences, excluding the info string. + +Options +: (`map`) The highlighting options from the info string. + +Ordinal +: (`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). + +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. + +## 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: + +```go-html-template {file="layouts/_default/_markup/render-codeblock.html" copy=true} +{{ $result := transform.HighlightCodeBlock . }} +{{ $result.Wrapped }} +``` + +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. + +```text +layouts/ +└── _default/ + └── _markup/ + ├── render-codeblock-mermaid.html + ├── render-codeblock-python.html + └── render-codeblock.html +``` + +For example, to create a code block render hook to render [Mermaid] diagrams: + +```go-html-template {file="layouts/_default/_markup/render-codeblock-mermaid.html" copy=true} +<pre class="mermaid"> + {{ .Inner | htmlEscape | safeHTML }} +</pre> +{{ .Page.Store.Set "hasMermaid" true }} +``` + +Then include this snippet at the _bottom_ of your base template, before the closing `body` tag: + +```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 }} +``` + +See the [diagrams] page for details. + +## 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 +[highlighting options]: /functions/transform/highlight/#options +[info string]: https://spec.commonmark.org/0.31.2/#info-string +[Mermaid]: https://mermaid.js.org/ diff --git a/docs/content/en/render-hooks/headings.md b/docs/content/en/render-hooks/headings.md new file mode 100755 index 000000000..89868d478 --- /dev/null +++ b/docs/content/en/render-hooks/headings.md @@ -0,0 +1,64 @@ +--- +title: Heading render hooks +linkTitle: Headings +description: Create a heading render hook to override the rendering of Markdown headings to HTML. +categories: [] +keywords: [] +--- + +## Context + +Heading render hook templates receive the following [context](g): + +Anchor +: (`string`) The `id` attribute of the heading element. + +Attributes +: (`map`) The [Markdown attributes], available if you configure your site as follows: + + {{< 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). + +PlainText +: (`string`) The heading text as plain text. + +Text +: (`template.HTML`) The heading text. + +[Markdown attributes]: /content-management/markdown-attributes/ +[`RenderShortcodes`]: /methods/page/rendershortcodes + +## 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/ + +```go-html-template {file="layouts/_default/_markup/render-heading.html" copy=true} +<h{{ .Level }} id="{{ .Anchor }}" {{- with .Attributes.class }} class="{{ . }}" {{- end }}> + {{- .Text -}} +</h{{ .Level }}> +``` + +To add an anchor link to the right of each heading: + +```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 }}> +``` + +{{% include "/_common/render-hooks/pageinner.md" %}} diff --git a/docs/content/en/render-hooks/images.md b/docs/content/en/render-hooks/images.md new file mode 100755 index 000000000..a4faac672 --- /dev/null +++ b/docs/content/en/render-hooks/images.md @@ -0,0 +1,138 @@ +--- +title: Image render hooks +linkTitle: Images +description: Create an image render to hook override the rendering of Markdown images to HTML. +categories: [] +keywords: [] +--- + +## Markdown + +A Markdown image has three components: the image description, the image destination, and optionally the image title. + +```text + + ------------ ------------------ --------- + description destination title +``` + +These components are passed into the render hook [context](g) as shown below. + +## Context + +Image render hook templates receive the following context: + +Attributes +: (`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 >}} + +Destination +: (`string`) The image destination. + +IsBlock +: (`bool`) Reports whether a standalone image is not wrapped within a paragraph element. + +Ordinal +: (`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). + +PlainText +: (`string`) The image description as plain text. + +Text +: (`template.HTML`) The image description. + +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. + +In its default configuration, Hugo renders Markdown images according to the [CommonMark specification]. To create a render hook that does the same thing: + +```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 */ -}} +``` + +To render standalone images within `figure` elements: + +```go-html-template {file="layouts/_default/_markup/render-image.html" copy=true} +{{- if .IsBlock -}} + <figure> + <img src="{{ .Destination | safeURL }}" + {{- with .PlainText }} alt="{{ . }}"{{ end -}} + > + {{- with .Title }}<figcaption>{{ . }}</figcaption>{{ end -}} + </figure> +{{- else -}} + <img src="{{ .Destination | safeURL }}" + {{- with .PlainText }} alt="{{ . }}"{{ end -}} + {{- with .Title }} title="{{ . }}"{{ end -}} + > +{{- end -}} +``` + +Note that the above requires the following site configuration: + +{{< code-toggle file=hugo >}} +[markup.goldmark.parser] +wrapStandAloneImageWithinParagraph = false +{{< /code-toggle >}} + +## Default + +{{< new-in 0.123.0 />}} + +Hugo includes an [embedded image render hook] to resolve Markdown image destinations. Disabled by default, you can enable it in your site configuration: + +{{< code-toggle file=hugo >}} +[markup.goldmark.renderHooks.image] +enableDefault = true +{{< /code-toggle >}} + +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. + +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. + +You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration: + +{{< code-toggle file=hugo >}} +[[module.mounts]] +source = 'assets' +target = 'assets' + +[[module.mounts]] +source = 'static' +target = 'assets' +{{< /code-toggle >}} + +Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations. + +{{% 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/ diff --git a/docs/content/en/render-hooks/introduction.md b/docs/content/en/render-hooks/introduction.md new file mode 100755 index 000000000..045d25c3d --- /dev/null +++ b/docs/content/en/render-hooks/introduction.md @@ -0,0 +1,81 @@ +--- +title: Introduction +description: An introduction to Hugo's render hooks. +categories: [] +keywords: [] +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: + +- [Blockquotes](/render-hooks/blockquotes) +- [Code blocks](/render-hooks/code-blocks) +- [Headings](/render-hooks/headings) +- [Images](/render-hooks/images) +- [Links](/render-hooks/links) +- [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. + +For example, consider this Markdown: + +```text +[Hugo](https://gohugo.io) + + +``` + +Without link or image render hooks, the example above is rendered to: + +```html +<p><a href="https://gohugo.io">Hugo</a></p> +<p><img alt="kitten" src="kitten.jpg"></p> +``` + +By creating link and image render hooks, you can alter the conversion from Markdown to HTML. For example: + +```html +<p><a href="https://gohugo.io" rel="external">Hugo</a></p> +<p><img alt="kitten" src="kitten.jpg" width="600" height="400"></p> +``` + +Each render hook is a template, with one template for each supported element type: + +```text +layouts/ +└── _default/ + └── _markup/ + ├── render-blockquote.html + ├── render-codeblock.html + ├── render-heading.html + ├── render-image.html + ├── render-link.html + ├── render-passthrough.html + └── render-table.html +``` + +The template lookup order allows you to create different render hooks for each page [type](g), [kind](g), language, and [output format](g). For example: + +```text +layouts/ +├── _default/ +│ └── _markup/ +│ ├── render-link.html +│ └── render-link.rss.xml +├── books/ +│ └── _markup/ +│ ├── render-link.html +│ └── render-link.rss.xml +└── films/ + └── _markup/ + ├── render-link.html + └── render-link.rss.xml +``` + +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/ diff --git a/docs/content/en/render-hooks/links.md b/docs/content/en/render-hooks/links.md new file mode 100755 index 000000000..23f725eb7 --- /dev/null +++ b/docs/content/en/render-hooks/links.md @@ -0,0 +1,108 @@ +--- +title: Link render hooks +linkTitle: Links +description: Create a link render hook to override the rendering of Markdown links to HTML. +categories: [] +keywords: [] +--- + +## Markdown + +A Markdown link has three components: the link text, the link destination, and optionally the link title. + +```text +[Post 1](/posts/post-1 "My first post") + ------ ------------- ------------- + text destination title +``` + +These components are passed into the render hook [context](g) as shown below. + +## Context + +Link render hook templates receive the following context: + +Destination +: (`string`) The link destination. + +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 link description as plain text. + +Text +: (`template.HTML`) The link description. + +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. + +In its default configuration, Hugo renders Markdown links according to the [CommonMark specification]. To create a render hook that does the same thing: + +```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 */ -}} +``` + +To include a `rel` attribute set to `external` for external links: + +```go-html-template {file="layouts/_default/_markup/render-link.html" copy=true} +{{- $u := urls.Parse .Destination -}} +<a href="{{ .Destination | safeURL }}" + {{- with .Title }} title="{{ . }}"{{ end -}} + {{- if $u.IsAbs }} rel="external"{{ end -}} +> + {{- with .Text }}{{ . }}{{ end -}} +</a> +{{- /* chomp trailing newline */ -}} +``` + +## Default + +{{< new-in 0.123.0 />}} + +Hugo includes an [embedded link render hook] to resolve Markdown link destinations. Disabled by default, you can enable it in your site configuration: + +{{< code-toggle file=hugo >}} +[markup.goldmark.renderHooks.link] +enableDefault = true +{{< /code-toggle >}} + +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. + +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. + +You must place global resources in the `assets` directory. If you have placed your resources in the `static` directory, and you are unable or unwilling to move them, you must mount the `static` directory to the `assets` directory by including both of these entries in your site configuration: + +{{< code-toggle file=hugo >}} +[[module.mounts]] +source = 'assets' +target = 'assets' + +[[module.mounts]] +source = 'static' +target = 'assets' +{{< /code-toggle >}} + +{{% 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 %}} diff --git a/docs/content/en/render-hooks/passthrough.md b/docs/content/en/render-hooks/passthrough.md new file mode 100755 index 000000000..356a030af --- /dev/null +++ b/docs/content/en/render-hooks/passthrough.md @@ -0,0 +1,124 @@ +--- +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: [] +keywords: [] +--- + +{{< new-in 0.132.0 />}} + +## Overview + +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]: /configuration/markup/#passthrough + +Depending on your choice of delimiters, Hugo will classify a passthrough element as either _block_ or _inline_. Consider this contrived example: + +```text {file="content/example.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. +``` + +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 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/ + +To enable custom rendering of passthrough elements, create a passthrough render hook. + +## Context + +Passthrough render hook templates receive the following [context](g): + +Attributes +: (`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/ +[`RenderShortcodes`]: /methods/page/rendershortcodes + +## 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/ + +```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 }} + {{- else }} + {{- .Value }} + {{- $.Page.Store.Set "hasMath" true }} + {{- end }} +{{- end -}} +``` + +Then, in your base template, conditionally include the KaTeX CSS within the head element: + +```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> +``` + +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. + +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 "/_common/render-hooks/pageinner.md" %}} diff --git a/docs/content/en/render-hooks/tables.md b/docs/content/en/render-hooks/tables.md new file mode 100755 index 000000000..c7671aff4 --- /dev/null +++ b/docs/content/en/render-hooks/tables.md @@ -0,0 +1,100 @@ +--- +title: Table render hooks +linkTitle: Tables +description: Create a table render hook to override the rendering of Markdown tables to HTML. +categories: [] +keywords: [] +--- + +{{< new-in 0.134.0 />}} + +## Context + +Table render hook templates receive the following [context](g): + +Attributes +: (`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/ +[`RenderShortcodes`]: /methods/page/rendershortcodes + +## 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`. + +Text +: (`template.HTML`) The text within the table cell. + +## Example + +In its default configuration, Hugo renders Markdown tables according to the [GitHub Flavored Markdown specification]. To create a render hook that does the same thing: + +[GitHub Flavored Markdown specification]: https://github.github.com/gfm/#tables-extension- + +```go-html-template {file="layouts/_default/_markup/render-table.html" copy=true} +<table + {{- range $k, $v := .Attributes }} + {{- if $v }} + {{- printf " %s=%q" $k $v | safeHTMLAttr }} + {{- end }} + {{- end }}> + <thead> + {{- range .THead }} + <tr> + {{- range . }} + <th + {{- with .Alignment }} + {{- printf " style=%q" (printf "text-align: %s" .) | safeHTMLAttr }} + {{- end -}} + > + {{- .Text -}} + </th> + {{- end }} + </tr> + {{- end }} + </thead> + <tbody> + {{- range .TBody }} + <tr> + {{- range . }} + <td + {{- with .Alignment }} + {{- printf " style=%q" (printf "text-align: %s" .) | safeHTMLAttr }} + {{- end -}} + > + {{- .Text -}} + </td> + {{- end }} + </tr> + {{- end }} + </tbody> +</table> +``` + +{{% include "/_common/render-hooks/pageinner.md" %}} |