Squashed 'docs/' changes from a49697e53..ccb1b97cb - hugo - [fork] hugo port for 9front
(HTM) git clone git@git.drkhsh.at/hugo.git
(DIR) Log
(DIR) Files
(DIR) Refs
(DIR) Submodules
(DIR) README
(DIR) LICENSE
---
(DIR) commit 39fd3b557014e339bc6c68a7ff34a7734a735ee0
(DIR) parent dec8cd4ada29218971743333f8ac662a9c06aad8
(HTM) Author: Bjørn Erik Pedersen <bjorn.erik.pedersen@gmail.com>
Date: Wed, 4 Sep 2024 18:52:05 +0200
Squashed 'docs/' changes from a49697e53..ccb1b97cb
ccb1b97cb Update blockquotes.md
a5f51431c Add new-in label
39dac5838 Document ContentWithoutSummary
de3c75694 Clarify blockquote render hook Markdown syntax
d32f7856d Document change to data type returned by render hook Text methods
83fe7ccc3 Document table render hooks
601234147 netlify: Hugo 0.134.0
a583640a0 Add support for Obsidian type blockquote alerts
3e0080861 Merge commit 'dec8cd4ada29218971743333f8ac662a9c06aad8'
2dde06576 output: Fix docshelper template lookup order for AMP pages
git-subtree-dir: docs
git-subtree-split: ccb1b97cbb11e60aab0108b33a270cccdd2218f6
Diffstat:
M content/en/about/features.md | 2 +-
M content/en/content-management/summ… | 10 +++++-----
M content/en/methods/page/Content.md | 6 +++---
A content/en/methods/page/ContentWit… | 28 ++++++++++++++++++++++++++++
M content/en/methods/page/Plain.md | 4 +++-
M content/en/methods/page/PlainWords… | 3 +++
M content/en/methods/page/RawContent… | 2 ++
M content/en/methods/page/RenderShor… | 4 +++-
M content/en/render-hooks/blockquote… | 62 ++++++++++++++++++++++++-------
M content/en/render-hooks/headings.md | 6 +++---
M content/en/render-hooks/images.md | 4 ++--
M content/en/render-hooks/introducti… | 5 ++++-
M content/en/render-hooks/links.md | 8 ++++----
A content/en/render-hooks/tables.md | 106 ++++++++++++++++++++++++++++++
M netlify.toml | 2 +-
15 files changed, 217 insertions(+), 35 deletions(-)
---
(DIR) diff --git a/content/en/about/features.md b/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.
(DIR) diff --git a/content/en/content-management/summaries.md b/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
(DIR) diff --git a/content/en/methods/page/Content.md b/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 }}
(DIR) diff --git a/content/en/methods/page/ContentWithoutSummary.md b/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.
(DIR) diff --git a/content/en/methods/page/Plain.md b/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.
(DIR) diff --git a/content/en/methods/page/PlainWords.md b/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]
---
(DIR) diff --git a/content/en/methods/page/RawContent.md b/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
(DIR) diff --git a/content/en/methods/page/RenderShortcodes.md b/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
(DIR) diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md
@@ -24,6 +24,18 @@ Blockquote render hook templates receive the following [context]:
(`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:
@@ -45,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
@@ -54,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
@@ -68,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 >}}
@@ -77,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">
@@ -96,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]
@@ -115,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 the GitHub Alert Markdown extension.
+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 %}}
+### Example
-The first line of each alert is an alert designator consisting of an exclamation point followed by the alert type, wrapped within brackets.
-
-The blockquote render hook below renders a multilingual alert if an alert desginator 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
@@ -138,13 +169,17 @@ The blockquote render hook below renders a multilingual alert if an alert desgin
<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 >}}
@@ -159,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
@@ -169,3 +203,5 @@ layouts/
├── render-blockquote-alert.html
└── render-blockquote-regular.html
```
+
+{{% include "/render-hooks/_common/pageinner.md" %}}
(DIR) diff --git a/content/en/render-hooks/headings.md b/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 >}}
(DIR) diff --git a/content/en/render-hooks/images.md b/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
(DIR) diff --git a/content/en/render-hooks/introduction.md b/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:
(DIR) diff --git a/content/en/render-hooks/links.md b/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
(DIR) diff --git a/content/en/render-hooks/tables.md b/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" %}}
(DIR) diff --git a/netlify.toml b/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"