mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
Merge commit '39fd3b557014e339bc6c68a7ff34a7734a735ee0'
This commit is contained in:
Bjørn Erik Pedersen
commit
b570a5f118
15 changed files with 207 additions and 39 deletions
|
|
@ -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.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
|
|
@ -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 }}
|
||||
|
|
|
|||
28
docs/content/en/methods/page/ContentWithoutSummary.md
Normal file
28
docs/content/en/methods/page/ContentWithoutSummary.md
Normal 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.
|
||||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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]
|
||||
---
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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) }}
|
||||
{{ 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" %}}
|
||||
|
|
|
|||
|
|
@ -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 >}}
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
106
docs/content/en/render-hooks/tables.md
Executable file
106
docs/content/en/render-hooks/tables.md
Executable 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" %}}
|
||||
|
|
@ -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"
|
||||
|
|
|
|||
Loading…
Reference in a new issue