Merge commit '39fd3b557014e339bc6c68a7ff34a7734a735ee0'

This commit is contained in:
Bjørn Erik Pedersen 2024-09-04 18:57:34 +02:00
commit b570a5f118
No known key found for this signature in database
15 changed files with 207 additions and 39 deletions

View file

@ -49,7 +49,7 @@ toc: true
: Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more. : Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
[Markdown render hooks] [Markdown render hooks]
: Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, and links. For example, render every standalone image as an HTML `figure` element. : Override the conversion of Markdown to HTML when rendering blockquotes, fenced code blocks, headings, images, links, and tables. For example, render every standalone image as an HTML `figure` element.
[Diagrams] [Diagrams]
: Use fenced code blocks and Markdown render hooks to include diagrams in your content. : Use fenced code blocks and Markdown render hooks to include diagrams in your content.

View file

@ -92,11 +92,11 @@ Note that the `summaryLength` is an approximate number of words.
Each summary type has different characteristics: Each summary type has different characteristics:
Type|Precedence|Renders markdown|Renders shortcodes|Strips HTML tags|Wraps single lines with `<p>` Type|Precedence|Renders markdown|Renders shortcodes|Wraps single lines with `<p>`
:--|:-:|:-:|:-:|:-:|:-: :--|:-:|:-:|:-:|:-:
Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark: Manual|1|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
Front&nbsp;matter|2|:heavy_check_mark:|:x:|:x:|:x: Front&nbsp;matter|2|:heavy_check_mark:|:x:|:x:
Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x: Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:
## Rendering ## Rendering

View file

@ -5,6 +5,8 @@ categories: []
keywords: [] keywords: []
action: action:
related: related:
- methods/page/Summary
- methods/page/ContentWithoutSummary
- methods/page/RawContent - methods/page/RawContent
- methods/page/Plain - methods/page/Plain
- methods/page/PlainWords - methods/page/PlainWords
@ -13,9 +15,7 @@ action:
signatures: [PAGE.Content] signatures: [PAGE.Content]
--- ---
The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. The content does not include front matter. The `Content` method on a `Page` object renders Markdown and shortcodes to HTML.
[shortcodes]: /getting-started/glossary/#shortcode
```go-html-template ```go-html-template
{{ .Content }} {{ .Content }}

View file

@ -0,0 +1,28 @@
---
title: ContentWithoutSummary
description: Returns the rendered content of the given page, excluding the content summary.
categories: []
keywords: []
action:
related:
- methods/page/Content
- methods/page/Summary
- methods/page/RawContent
- methods/page/Plain
- methods/page/PlainWords
- methods/page/RenderShortcodes
returnType: template.HTML
signatures: [PAGE.ContentWithoutSummary]
---
{{< new-in 0.134.0 >}}
Applicable when using manual or automatic [content summaries], the `ContentWithoutSummary` method on a `Page` object renders Markdown and shortcodes to HTML, excluding the content summary from the result.
[content summaries]: /content-management/summaries/#manual-summary
```go-html-template
{{ .ContentWithoutSummary }}
```
The `ContentWithoutSummary` method returns an empty string if you define the content summary in front matter.

View file

@ -6,6 +6,8 @@ keywords: []
action: action:
related: related:
- methods/page/Content - methods/page/Content
- methods/page/Summary
- methods/page/ContentWithoutSummary
- methods/page/RawContent - methods/page/RawContent
- methods/page/PlainWords - methods/page/PlainWords
- methods/page/RenderShortcodes - methods/page/RenderShortcodes
@ -13,7 +15,7 @@ action:
signatures: [PAGE.Plain] signatures: [PAGE.Plain]
--- ---
The `Plain` method on a `Page` object renders Markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities]. The plain content does not include front matter. The `Plain` method on a `Page` object renders Markdown and [shortcodes] to HTML, then strips the HTML [tags]. It does not strip HTML [entities].
To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function. To prevent Go's [html/template] package from escaping HTML entities, pass the result through the [`htmlUnescape`] function.

View file

@ -6,8 +6,11 @@ keywords: []
action: action:
related: related:
- methods/page/Content - methods/page/Content
- methods/page/Summary
- methods/page/ContentWithoutSummary
- methods/page/RawContent - methods/page/RawContent
- methods/page/Plain - methods/page/Plain
- methods/page/RenderShortcodes
returnType: '[]string' returnType: '[]string'
signatures: [PAGE.PlainWords] signatures: [PAGE.PlainWords]
--- ---

View file

@ -6,6 +6,8 @@ keywords: []
action: action:
related: related:
- methods/page/Content - methods/page/Content
- methods/page/Summary
- methods/page/ContentWithoutSummary
- methods/page/Plain - methods/page/Plain
- methods/page/PlainWords - methods/page/PlainWords
- methods/page/RenderShortcodes - methods/page/RenderShortcodes

View file

@ -5,11 +5,13 @@ categories: []
keywords: [] keywords: []
action: action:
related: related:
- methods/page/RenderString
- methods/page/Content - methods/page/Content
- methods/page/Summary
- methods/page/ContentWithoutSummary
- methods/page/RawContent - methods/page/RawContent
- methods/page/Plain - methods/page/Plain
- methods/page/PlainWords - methods/page/PlainWords
- methods/page/RenderString
returnType: template.HTML returnType: template.HTML
signatures: [PAGE.RenderShortcodes] signatures: [PAGE.RenderShortcodes]
toc: true toc: true

View file

@ -28,15 +28,13 @@ Blockquote render hook templates receive the following [context]:
{{< new-in 0.134.0 >}} {{< new-in 0.134.0 >}}
(`hstring.HTML`) Applicable when [`Type`](#type) is `alert` when using [Obsidian callouts] syntax, this is the alert title converted to HTML. (`template.HTML`) Applicable when [`Type`](#type) is `alert`, this is the alert title. See the [alerts](#alerts) section below.
###### AlertSign ###### AlertSign
{{< new-in 0.134.0 >}} {{< new-in 0.134.0 >}}
(`string`) Applicable when [`Type`](#type) is `alert` when using [Obsidian callouts] syntax, this is one of "+", "-" or "" (empty string) to indicate the presence of a foldable sign. (`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&nbsp;`+`,&nbsp;`-`,&nbsp;or an empty string. See the [alerts](#alerts) section below.
[Obsidian callouts]: https://help.obsidian.md/Editing+and+formatting/Callouts
###### Attributes ###### Attributes
@ -59,7 +57,7 @@ block = true
###### PageInner ###### PageInner
(`page`) A reference to a page nested via the [`RenderShortcodes`] method. (`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner-details).
[`RenderShortcodes`]: /methods/page/rendershortcodes [`RenderShortcodes`]: /methods/page/rendershortcodes
@ -68,7 +66,7 @@ block = true
(`string`) The position of the blockquote within the page content. (`string`) The position of the blockquote within the page content.
###### Text ###### Text
(`string`) The blockquote text, excluding the alert designator if present. See the [alerts](#alerts) section below. (`template.HTML`) The blockquote text, excluding the first line if [`Type`](#type) is `alert`. See the [alerts](#alerts) section below.
###### Type ###### Type
@ -82,7 +80,7 @@ In its default configuration, Hugo renders Markdown blockquotes according to the
{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} {{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
<blockquote> <blockquote>
{{ .Text | safeHTML }} {{ .Text }}
</blockquote> </blockquote>
{{< /code >}} {{< /code >}}
@ -91,7 +89,7 @@ To render a blockquote as an HTML `figure` element with an optional citation and
{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} {{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
<figure> <figure>
<blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}> <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}>
{{ .Text | safeHTML }} {{ .Text }}
</blockquote> </blockquote>
{{ with .Attributes.caption }} {{ with .Attributes.caption }}
<figcaption class="blockquote-caption"> <figcaption class="blockquote-caption">
@ -110,7 +108,11 @@ Then in your markdown:
## Alerts ## Alerts
Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information. For example: 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:
{{< code file=content/example.md lang=text >}} {{< code file=content/example.md lang=text >}}
> [!NOTE] > [!NOTE]
@ -129,15 +131,30 @@ Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphas
> Advises about risks or negative outcomes of certain actions. > Advises about risks or negative outcomes of certain actions.
{{< /code >}} {{< /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&nbsp;`+`&nbsp;or&nbsp;`-`, typically used to indicate whether an alert is graphically foldable. For example:
{{< code file=content/example.md lang=text >}}
> [!WARNING]+ Radiation hazard
> Do not approach or handle without protective gear.
{{< /code >}}
The extended syntax is compatible with [Obsidian].
{{% note %}} {{% note %}}
This syntax is compatible with both the GitHub Alert Markdown extension and Obsidian's callout syntax. 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.
But note that GitHub will not recognize callouts with one of Obsidian's extensions (e.g. callout title or the foldable sign).
{{% /note %}} {{% /note %}}
The first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets. ### Example
The blockquote render hook below renders a multilingual alert if an alert designator is present, otherwise it renders a blockquote according to the CommonMark specification. 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 >}} {{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}}
{{ $emojis := dict {{ $emojis := dict
@ -152,13 +169,17 @@ The blockquote render hook below renders a multilingual alert if an alert design
<blockquote class="alert alert-{{ .AlertType }}"> <blockquote class="alert alert-{{ .AlertType }}">
<p class="alert-heading"> <p class="alert-heading">
{{ transform.Emojify (index $emojis .AlertType) }} {{ transform.Emojify (index $emojis .AlertType) }}
{{ or (i18n .AlertType) (title .AlertType) }} {{ with .AlertTitle }}
{{ . }}
{{ else }}
{{ or (i18n .AlertType) (title .AlertType) }}
{{ end }}
</p> </p>
{{ .Text | safeHTML }} {{ .Text }}
</blockquote> </blockquote>
{{ else }} {{ else }}
<blockquote> <blockquote>
{{ .Text | safeHTML }} {{ .Text }}
</blockquote> </blockquote>
{{ end }} {{ end }}
{{< /code >}} {{< /code >}}
@ -173,7 +194,6 @@ tip = 'Tip'
warning = 'Warning' warning = 'Warning'
{{< /code-toggle >}} {{< /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: 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 ```text
@ -183,3 +203,5 @@ layouts/
├── render-blockquote-alert.html ├── render-blockquote-alert.html
└── render-blockquote-regular.html └── render-blockquote-regular.html
``` ```
{{% include "/render-hooks/_common/pageinner.md" %}}

View file

@ -55,7 +55,7 @@ title = true
###### Text ###### Text
(`string`) The heading text. (`template.HTML`) The heading text.
## Examples ## Examples
@ -65,7 +65,7 @@ In its default configuration, Hugo renders Markdown headings according to the [C
{{< code file=layouts/_default/_markup/render-heading.html copy=true >}} {{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
<h{{ .Level }} id="{{ .Anchor }}"> <h{{ .Level }} id="{{ .Anchor }}">
{{- .Text | safeHTML -}} {{- .Text -}}
</h{{ .Level }}> </h{{ .Level }}>
{{< /code >}} {{< /code >}}
@ -73,7 +73,7 @@ To add an anchor link to the right of each heading:
{{< code file=layouts/_default/_markup/render-heading.html copy=true >}} {{< code file=layouts/_default/_markup/render-heading.html copy=true >}}
<h{{ .Level }} id="{{ .Anchor }}"> <h{{ .Level }} id="{{ .Anchor }}">
{{ .Text | safeHTML }} {{ .Text }}
<a href="#{{ .Anchor }}">#</a> <a href="#{{ .Anchor }}">#</a>
</h{{ .Level }}> </h{{ .Level }}>
{{< /code >}} {{< /code >}}

View file

@ -73,7 +73,7 @@ block = true
###### Text ###### Text
(`string`) The image description. (`template.HTML`) The image description.
###### Title ###### Title
@ -143,7 +143,7 @@ The embedded image render hook is automatically enabled for multilingual single-
[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles [duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
{{% /note %}} {{% /note %}}
The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource], falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if it is unable to resolve a destination. The embedded image render hook resolves internal Markdown destinations by looking for a matching [page resource], falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
[page resource]: /getting-started/glossary/#page-resource [page resource]: /getting-started/glossary/#page-resource
[global resource]: /getting-started/glossary/#global-resource [global resource]: /getting-started/glossary/#global-resource

View file

@ -19,6 +19,7 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend
- [Images](/render-hooks/images) - [Images](/render-hooks/images)
- [Links](/render-hooks/links) - [Links](/render-hooks/links)
- [Passthrough elements](/render-hooks/passthrough) - [Passthrough elements](/render-hooks/passthrough)
- [Tables](/render-hooks/tables)
{{% note %}} {{% note %}}
Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText. Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText.
@ -60,7 +61,9 @@ layouts/
├── render-codeblock.html ├── render-codeblock.html
├── render-heading.html ├── render-heading.html
├── render-image.html ├── render-image.html
└── render-link.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], [kind], language, and [output format]. For example: The template lookup order allows you to create different render hooks for each page [type], [kind], language, and [output format]. For example:

View file

@ -54,7 +54,7 @@ Link render hook templates receive the following context:
###### Text ###### Text
(`string`) The link description. (`template.HTML`) The link description.
###### Title ###### Title
@ -74,7 +74,7 @@ In its default configuration, Hugo renders Markdown links according to the [Comm
<a href="{{ .Destination | safeURL }}" <a href="{{ .Destination | safeURL }}"
{{- with .Title }} title="{{ . }}"{{ end -}} {{- with .Title }} title="{{ . }}"{{ end -}}
> >
{{- with .Text | safeHTML }}{{ . }}{{ end -}} {{- with .Text }}{{ . }}{{ end -}}
</a> </a>
{{- /* chomp trailing newline */ -}} {{- /* chomp trailing newline */ -}}
{{< /code >}} {{< /code >}}
@ -87,7 +87,7 @@ To include a `rel` attribute set to `external` for external links:
{{- with .Title }} title="{{ . }}"{{ end -}} {{- with .Title }} title="{{ . }}"{{ end -}}
{{- if $u.IsAbs }} rel="external"{{ end -}} {{- if $u.IsAbs }} rel="external"{{ end -}}
> >
{{- with .Text | safeHTML }}{{ . }}{{ end -}} {{- with .Text }}{{ . }}{{ end -}}
</a> </a>
{{- /* chomp trailing newline */ -}} {{- /* chomp trailing newline */ -}}
{{< /code >}} {{< /code >}}
@ -113,7 +113,7 @@ The embedded link render hook is automatically enabled for multilingual single-h
[duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles [duplication of shared page resources]: /getting-started/configuration-markup/#duplicateresourcefiles
{{% /note %}} {{% /note %}}
The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource], then falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if it is unable to resolve a destination. The embedded link render hook resolves internal Markdown destinations by looking for a matching page, falling back to a matching [page resource], then falling back to a matching [global resource]. Remote destinations are passed through, and the render hook will not throw an error or warning if unable to resolve a destination.
[page resource]: /getting-started/glossary/#page-resource [page resource]: /getting-started/glossary/#page-resource
[global resource]: /getting-started/glossary/#global-resource [global resource]: /getting-started/glossary/#global-resource

View file

@ -0,0 +1,106 @@
---
title: Table render hooks
linkTitle: Tables
description: Create a table render hook to override the rendering of Markdown tables to HTML.
categories: [render hooks]
keywords: []
menu:
docs:
parent: render-hooks
weight: 90
weight: 90
toc: true
---
{{< new-in 0.134.0 >}}
## Context
Table 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 >}}
###### 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`.
###### 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-
{{< code 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 {{ printf "style=%q" (printf "text-align: %s" .Alignment) | safeHTMLAttr }}>
{{- .Text -}}
</th>
{{- end }}
</tr>
{{- end }}
</thead>
<tbody>
{{- range .TBody }}
<tr>
{{- range . }}
<td {{ printf "style=%q" (printf "text-align: %s" .Alignment) | safeHTMLAttr }}>
{{- .Text -}}
</td>
{{- end }}
</tr>
{{- end }}
</tbody>
</table>
{{< /code >}}
{{% include "/render-hooks/_common/pageinner.md" %}}

View file

@ -3,7 +3,7 @@
command = "hugo --gc --minify" command = "hugo --gc --minify"
[build.environment] [build.environment]
HUGO_VERSION = "0.133.1" HUGO_VERSION = "0.134.0"
[context.production.environment] [context.production.environment]
HUGO_ENV = "production" HUGO_ENV = "production"