Merge commit '39fd3b557014e339bc6c68a7ff34a7734a735ee0'

gohugoio · Sep 4, 2024 · b570a5f · b570a5f
2 parents aacff7a + 39fd3b5
commit b570a5f
Show file tree

Hide file tree

Showing 15 changed files with 207 additions and 39 deletions.
diff --git 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
@@ -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&nbsp;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&nbsp;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
@@ -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
@@ -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
@@ -6,14 +6,16 @@ keywords: []
 action:
   related:
     - methods/page/Content
+    - methods/page/Summary
+    - methods/page/ContentWithoutSummary
     - methods/page/RawContent
     - methods/page/PlainWords
     - methods/page/RenderShortcodes
   returnType: string
   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
@@ -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
@@ -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
@@ -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
@@ -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&nbsp;`+`,&nbsp;`-`,&nbsp;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&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 %}}
-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
@@ -55,7 +55,7 @@ title = true
 
 ###### Text
 
-(`string`) The heading text.
+(`template.HTML`) The heading text.
 
 ## Examples
 
@@ -65,15 +65,15 @@ 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 >}}
 
 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
@@ -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
@@ -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
@@ -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