diff options
author | Bjørn Erik Pedersen <[email protected]> | 2024-09-04 18:57:34 +0200 |
---|---|---|
committer | Bjørn Erik Pedersen <[email protected]> | 2024-09-04 18:57:34 +0200 |
commit | b570a5f1184fe275ad6fc04b82050ad8fce95651 (patch) | |
tree | 7a7baf8a5e1c370f407a4e683ad5d5da712d6de2 | |
parent | aacff7aff4fefd88bc7da9f7e4517ca33a9bac7b (diff) | |
parent | 39fd3b557014e339bc6c68a7ff34a7734a735ee0 (diff) | |
download | hugo-b570a5f1184fe275ad6fc04b82050ad8fce95651.tar.gz hugo-b570a5f1184fe275ad6fc04b82050ad8fce95651.zip |
Merge commit '39fd3b557014e339bc6c68a7ff34a7734a735ee0'
-rw-r--r-- | docs/content/en/about/features.md | 2 | ||||
-rw-r--r-- | docs/content/en/content-management/summaries.md | 10 | ||||
-rw-r--r-- | docs/content/en/methods/page/Content.md | 6 | ||||
-rw-r--r-- | docs/content/en/methods/page/ContentWithoutSummary.md | 28 | ||||
-rw-r--r-- | docs/content/en/methods/page/Plain.md | 4 | ||||
-rw-r--r-- | docs/content/en/methods/page/PlainWords.md | 3 | ||||
-rw-r--r-- | docs/content/en/methods/page/RawContent.md | 2 | ||||
-rw-r--r-- | docs/content/en/methods/page/RenderShortcodes.md | 4 | ||||
-rwxr-xr-x | docs/content/en/render-hooks/blockquotes.md | 56 | ||||
-rwxr-xr-x | docs/content/en/render-hooks/headings.md | 6 | ||||
-rwxr-xr-x | docs/content/en/render-hooks/images.md | 4 | ||||
-rwxr-xr-x | docs/content/en/render-hooks/introduction.md | 5 | ||||
-rwxr-xr-x | docs/content/en/render-hooks/links.md | 8 | ||||
-rwxr-xr-x | docs/content/en/render-hooks/tables.md | 106 | ||||
-rw-r--r-- | docs/netlify.toml | 2 |
15 files changed, 207 insertions, 39 deletions
diff --git a/docs/content/en/about/features.md b/docs/content/en/about/features.md index 835384723..58d324853 100644 --- a/docs/content/en/about/features.md +++ b/docs/content/en/about/features.md @@ -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. [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] : Use fenced code blocks and Markdown render hooks to include diagrams in your content. diff --git a/docs/content/en/content-management/summaries.md b/docs/content/en/content-management/summaries.md index 7b81cf0a0..e0b2c9590 100644 --- a/docs/content/en/content-management/summaries.md +++ b/docs/content/en/content-management/summaries.md @@ -92,11 +92,11 @@ Note that the `summaryLength` is an approximate number of words. Each summary type has different characteristics: -Type|Precedence|Renders markdown|Renders shortcodes|Strips HTML tags|Wraps single lines with `<p>` -:--|:-:|:-:|:-:|:-:|:-: -Manual|1|:heavy_check_mark:|:heavy_check_mark:|:x:|:heavy_check_mark: -Front matter|2|:heavy_check_mark:|:x:|:x:|:x: -Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark:|:x: +Type|Precedence|Renders markdown|Renders shortcodes|Wraps single lines with `<p>` +:--|:-:|:-:|:-:|:-: +Manual|1|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: +Front matter|2|:heavy_check_mark:|:x:|:x: +Automatic|3|:heavy_check_mark:|:heavy_check_mark:|:heavy_check_mark: ## Rendering diff --git a/docs/content/en/methods/page/Content.md b/docs/content/en/methods/page/Content.md index a9d38367c..373c6590a 100644 --- a/docs/content/en/methods/page/Content.md +++ b/docs/content/en/methods/page/Content.md @@ -5,6 +5,8 @@ categories: [] keywords: [] action: related: + - methods/page/Summary + - methods/page/ContentWithoutSummary - methods/page/RawContent - methods/page/Plain - methods/page/PlainWords @@ -13,9 +15,7 @@ action: signatures: [PAGE.Content] --- -The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. The content does not include front matter. - -[shortcodes]: /getting-started/glossary/#shortcode +The `Content` method on a `Page` object renders Markdown and shortcodes to HTML. ```go-html-template {{ .Content }} diff --git a/docs/content/en/methods/page/ContentWithoutSummary.md b/docs/content/en/methods/page/ContentWithoutSummary.md new file mode 100644 index 000000000..5080f6717 --- /dev/null +++ b/docs/content/en/methods/page/ContentWithoutSummary.md @@ -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. diff --git a/docs/content/en/methods/page/Plain.md b/docs/content/en/methods/page/Plain.md index 3aae1ed61..06d2bde48 100644 --- a/docs/content/en/methods/page/Plain.md +++ b/docs/content/en/methods/page/Plain.md @@ -6,6 +6,8 @@ keywords: [] action: related: - methods/page/Content + - methods/page/Summary + - methods/page/ContentWithoutSummary - methods/page/RawContent - methods/page/PlainWords - methods/page/RenderShortcodes @@ -13,7 +15,7 @@ action: 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. diff --git a/docs/content/en/methods/page/PlainWords.md b/docs/content/en/methods/page/PlainWords.md index 4f70193fe..221fd741b 100644 --- a/docs/content/en/methods/page/PlainWords.md +++ b/docs/content/en/methods/page/PlainWords.md @@ -6,8 +6,11 @@ keywords: [] action: related: - methods/page/Content + - methods/page/Summary + - methods/page/ContentWithoutSummary - methods/page/RawContent - methods/page/Plain + - methods/page/RenderShortcodes returnType: '[]string' signatures: [PAGE.PlainWords] --- diff --git a/docs/content/en/methods/page/RawContent.md b/docs/content/en/methods/page/RawContent.md index 12686c695..e4ab8a28e 100644 --- a/docs/content/en/methods/page/RawContent.md +++ b/docs/content/en/methods/page/RawContent.md @@ -6,6 +6,8 @@ keywords: [] action: related: - methods/page/Content + - methods/page/Summary + - methods/page/ContentWithoutSummary - methods/page/Plain - methods/page/PlainWords - methods/page/RenderShortcodes diff --git a/docs/content/en/methods/page/RenderShortcodes.md b/docs/content/en/methods/page/RenderShortcodes.md index a4120f69a..9679fc8d5 100644 --- a/docs/content/en/methods/page/RenderShortcodes.md +++ b/docs/content/en/methods/page/RenderShortcodes.md @@ -5,11 +5,13 @@ categories: [] keywords: [] action: related: - - methods/page/RenderString - methods/page/Content + - methods/page/Summary + - methods/page/ContentWithoutSummary - methods/page/RawContent - methods/page/Plain - methods/page/PlainWords + - methods/page/RenderString returnType: template.HTML signatures: [PAGE.RenderShortcodes] toc: true diff --git a/docs/content/en/render-hooks/blockquotes.md b/docs/content/en/render-hooks/blockquotes.md index 607514f04..143c536d1 100755 --- a/docs/content/en/render-hooks/blockquotes.md +++ b/docs/content/en/render-hooks/blockquotes.md @@ -28,15 +28,13 @@ Blockquote render hook templates receive the following [context]: {{< 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 {{< 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. - -[Obsidian callouts]: https://help.obsidian.md/Editing+and+formatting/Callouts +(`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 @@ -59,7 +57,7 @@ block = true ###### 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 @@ -68,7 +66,7 @@ block = true (`string`) The position of the blockquote within the page content. ###### 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 @@ -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 >}} <blockquote> - {{ .Text | safeHTML }} + {{ .Text }} </blockquote> {{< /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 >}} <figure> <blockquote {{ with .Attributes.cite }}cite="{{ . }}"{{ end }}> - {{ .Text | safeHTML }} + {{ .Text }} </blockquote> {{ with .Attributes.caption }} <figcaption class="blockquote-caption"> @@ -110,7 +108,11 @@ Then in your markdown: ## 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 >}} > [!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. {{< /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 >}} +> [!WARNING]+ Radiation hazard +> Do not approach or handle without protective gear. +{{< /code >}} + +The extended syntax is compatible with [Obsidian]. {{% note %}} -This syntax is compatible with both the GitHub Alert Markdown extension and Obsidian's callout syntax. -But note that GitHub will not recognize callouts with one of Obsidian's extensions (e.g. callout title or the foldable sign). +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 %}} -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 >}} {{ $emojis := dict @@ -152,13 +169,17 @@ The blockquote render hook below renders a multilingual alert if an alert design <blockquote class="alert alert-{{ .AlertType }}"> <p class="alert-heading"> {{ transform.Emojify (index $emojis .AlertType) }} - {{ or (i18n .AlertType) (title .AlertType) }} + {{ with .AlertTitle }} + {{ . }} + {{ else }} + {{ or (i18n .AlertType) (title .AlertType) }} + {{ end }} </p> - {{ .Text | safeHTML }} + {{ .Text }} </blockquote> {{ else }} <blockquote> - {{ .Text | safeHTML }} + {{ .Text }} </blockquote> {{ end }} {{< /code >}} @@ -173,7 +194,6 @@ 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 @@ -183,3 +203,5 @@ layouts/ ├── render-blockquote-alert.html └── render-blockquote-regular.html ``` + +{{% include "/render-hooks/_common/pageinner.md" %}} diff --git a/docs/content/en/render-hooks/headings.md b/docs/content/en/render-hooks/headings.md index 8ae3b808a..dc64296ea 100755 --- a/docs/content/en/render-hooks/headings.md +++ b/docs/content/en/render-hooks/headings.md @@ -55,7 +55,7 @@ title = true ###### Text -(`string`) The heading text. +(`template.HTML`) The heading text. ## 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 >}} <h{{ .Level }} id="{{ .Anchor }}"> - {{- .Text | safeHTML -}} + {{- .Text -}} </h{{ .Level }}> {{< /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 >}} <h{{ .Level }} id="{{ .Anchor }}"> - {{ .Text | safeHTML }} + {{ .Text }} <a href="#{{ .Anchor }}">#</a> </h{{ .Level }}> {{< /code >}} diff --git a/docs/content/en/render-hooks/images.md b/docs/content/en/render-hooks/images.md index 1638ceeae..eca346c10 100755 --- a/docs/content/en/render-hooks/images.md +++ b/docs/content/en/render-hooks/images.md @@ -73,7 +73,7 @@ block = true ###### Text -(`string`) The image description. +(`template.HTML`) The image description. ###### 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 {{% /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 [global resource]: /getting-started/glossary/#global-resource diff --git a/docs/content/en/render-hooks/introduction.md b/docs/content/en/render-hooks/introduction.md index 3745fc398..2d1598fcb 100755 --- a/docs/content/en/render-hooks/introduction.md +++ b/docs/content/en/render-hooks/introduction.md @@ -19,6 +19,7 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend - [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. @@ -60,7 +61,9 @@ layouts/ ├── render-codeblock.html ├── render-heading.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: diff --git a/docs/content/en/render-hooks/links.md b/docs/content/en/render-hooks/links.md index 79c3d6926..9505e989b 100755 --- a/docs/content/en/render-hooks/links.md +++ b/docs/content/en/render-hooks/links.md @@ -54,7 +54,7 @@ Link render hook templates receive the following context: ###### Text -(`string`) The link description. +(`template.HTML`) The link description. ###### Title @@ -74,7 +74,7 @@ In its default configuration, Hugo renders Markdown links according to the [Comm <a href="{{ .Destination | safeURL }}" {{- with .Title }} title="{{ . }}"{{ end -}} > - {{- with .Text | safeHTML }}{{ . }}{{ end -}} + {{- with .Text }}{{ . }}{{ end -}} </a> {{- /* chomp trailing newline */ -}} {{< /code >}} @@ -87,7 +87,7 @@ To include a `rel` attribute set to `external` for external links: {{- with .Title }} title="{{ . }}"{{ end -}} {{- if $u.IsAbs }} rel="external"{{ end -}} > - {{- with .Text | safeHTML }}{{ . }}{{ end -}} + {{- with .Text }}{{ . }}{{ end -}} </a> {{- /* chomp trailing newline */ -}} {{< /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 {{% /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 [global resource]: /getting-started/glossary/#global-resource diff --git a/docs/content/en/render-hooks/tables.md b/docs/content/en/render-hooks/tables.md new file mode 100755 index 000000000..41eadad7b --- /dev/null +++ b/docs/content/en/render-hooks/tables.md @@ -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" %}} diff --git a/docs/netlify.toml b/docs/netlify.toml index 44c10a3c9..2780fe747 100644 --- a/docs/netlify.toml +++ b/docs/netlify.toml @@ -3,7 +3,7 @@ command = "hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.133.1" + HUGO_VERSION = "0.134.0" [context.production.environment] HUGO_ENV = "production" |