From 82b5586fb3f0c189e62f63bd2394d7133b6f8500 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Sun, 11 Aug 2024 12:42:07 +0200 Subject: [PATCH 01/36] Document transform.ToMath --- content/en/functions/transform/ToMath.md | 117 +++++++++++++++++++++++ 1 file changed, 117 insertions(+) create mode 100644 content/en/functions/transform/ToMath.md diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md new file mode 100644 index 000000000..8ae2f4d33 --- /dev/null +++ b/content/en/functions/transform/ToMath.md @@ -0,0 +1,117 @@ +--- +title: transform.ToMath +description: Renders a math expression using KaTeX. +categories: [] +keywords: [] +action: + aliases: [] + related: + - content-management/mathematics + returnType: types.Result[template.HTML] + signatures: ['transform.ToMath EXPRESSION [OPTIONS]'] +aliases: [/functions/tomath] +toc: true +--- + +{{< new-in "0.132.0" >}} + +{{% note %}} +This feature was introduced in Hugo 0.132.0 and is marked as experimental. + +This does not mean that it's going to be removed, but this is our first use of WASI/Wasm in Hugo, and we need to see how it [works in the wild](https://github.com/gohugoio/hugo/issues/12736) before we can set it in stone. +{{% /note %}} + +## Arguments + +EXPRESSION +: The math expression to render using KaTeX. + +OPTIONS +: A map of zero or more [options]. + +## Options + +These are a sub set of the [KaTeX options]. + +output +: String. Default is `mathml`.\ +`html` Outputs HTML only.\ +`mathml`: Outputs MathML only.\ +`htmlAndMathml`: Outputs HTML for visual rendering and MathML for accessibility. + +displayMode +: Boolean. Default is `false`.\ +If `true` the math will be rendered in display mode. If false the math will be rendered in `inline` mode. + +leqno +: Boolean. Default is `false`.\ +If `true` the math will be rendered with the equation numbers on the left. + +fleqn +: Boolean. Default is `false`.\ +If `true`, render flush left with a 2em left margin. + +minRuleThickness +: Float. Default is `0.04`.\ +The minimum thickness of the fraction lines in `em`. + +macros +: Map. Default is `{}`.\ +A map of macros to be used in the math expression. + +throwOnError +: Boolean. Default is `true`.\ +If `true`, KaTeX will throw a `ParseError` when it encounters an unsupported command or invalid LaTex. See [error handling]. + +errorColor +: String. Default is `#cc0000`.\ +The color of the error messages.\ +A color string given in the format "#XXX" or "#XXXXXX" + + +## Examples + +### Basic + +```go-html-template +{{ transform.ToMath "c = \\pm\\sqrt{a^2 + b^2}" }} +``` + +### Macros + +```go-html-template +{{ $macros := dict + "\\addBar" "\\bar{#1}" + "\\bold" "\\mathbf{#1}" +}} +{{ $opts := dict "macros" $macros }} +{{ transform.ToMath "\\addBar{y} + \\bold{H}" $opts }} +``` + +## Error handling + +There are 3 ways to handle errors from KaTeX: + +1. Let KaTeX throw an error and make the build fail. This is the default behavior. +1. Handle the error in your template. See the render hook example below. +1. Set the `throwOnError` option to `false` to make KaTeX render the expression as an error instead of throwing an error. See [options]. + +{{< code file=layouts/_default/_markup/render-passthrough-inline.html copy=true >}} +{{ with transform.ToMath .Inner }} + {{ with .Err }} + {{ errorf "Failed to render KaTeX: %q. See %s" . $.Position }} + {{ else }} + {{ . }} + {{ end }} +{{ end }} +{{- /* chomp trailing newline */ -}} +{{< /code >}} + + + +[options]: #options +[error handling]: #error-handling +[KaTeX options]: https://katex.org/docs/options.html + + + From 160f22d0e9f49b85afab7efc97b79a2df3e7d6a2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Mon, 12 Aug 2024 17:50:45 +0200 Subject: [PATCH 02/36] netlify: Hugo 0.132.0 --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index f7f1a5f04..42618fbfd 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ command = "hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.131.0" + HUGO_VERSION = "0.132.0" [context.production.environment] HUGO_ENV = "production" From 8f5afb55d5b89d6b05dc7bae0ecd99f1609b5635 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Mon, 12 Aug 2024 09:13:32 -0700 Subject: [PATCH 03/36] Update plainify return type This was changed from string to template.HTML in v0.132.0. --- content/en/functions/transform/Plainify.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/functions/transform/Plainify.md b/content/en/functions/transform/Plainify.md index 040145170..681d41f72 100644 --- a/content/en/functions/transform/Plainify.md +++ b/content/en/functions/transform/Plainify.md @@ -6,7 +6,7 @@ keywords: [] action: aliases: [plainify] related: [] - returnType: string + returnType: template.HTML signatures: [transform.Plainify INPUT] aliases: [/functions/plainify] --- From 2dae7212874ead12f2043169753301e79e4cc8ef Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 14 Jun 2024 09:07:14 -0700 Subject: [PATCH 04/36] Document blockquote render hooks --- content/en/render-hooks/blockquotes.md | 163 +++++++++++++++++++++++++ content/en/render-hooks/code-blocks.md | 4 +- content/en/render-hooks/headings.md | 8 +- content/en/render-hooks/images.md | 8 +- content/en/render-hooks/links.md | 4 +- 5 files changed, 177 insertions(+), 10 deletions(-) create mode 100755 content/en/render-hooks/blockquotes.md diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md new file mode 100755 index 000000000..fd9a837d5 --- /dev/null +++ b/content/en/render-hooks/blockquotes.md @@ -0,0 +1,163 @@ +--- +title: Blockquote render hooks +linkTitle: Blockquotes +description: Create a blockquote render hook to override the rendering of Markdown blockquotes to HTML. +categories: [render hooks] +keywords: [] +menu: + docs: + parent: render-hooks + weight: 30 +weight: 30 +toc: true +--- + +## Context + +Blockquote render hook templates receive the following [context]: + +[context]: /getting-started/glossary/#context + +###### AlertType + +(`string`) Applicable when [`Type`](#type) is `alert`, this is the alert type converted to lowercase. See the [alerts](#alerts) section below. + +###### 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 blockquote on the page. + +###### Page + +(`page`) A reference to the current page. + +###### Position + +(`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. + +###### Type + +(`bool`) The blockquote type. Returns `alert` if the blockquote has an alert designator, else `regular`. See the [alerts](#alerts) section below. + +## Examples + +In its default configuration, Hugo renders Markdown blockquotes according to the [CommonMark specification]. To create a render hook that does the same thing: + +[CommonMark specification]: https://spec.commonmark.org/current/ + +{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +
+ {{ .Text | safeHTML }} +
+{{< /code >}} + +To render a blockquote as an HTML `figure` element with an optional citation and caption: + +{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +
+
+ {{ .Text | safeHTML }} +
+ {{ with .Attributes.caption }} +
+ {{ . | safeHTML }} +
+ {{ end }} +
+{{< /code >}} + +Then in your markdown: + +```text +> Some text +{cite="https://gohugo.io" caption="Some caption"} +``` + +## Alerts + +Also known as _callouts_ or _admonitions_, alerts are blockquotes used to emphasize critical information. For example: + +{{< code file=content/example.md lang=text >}} +> [!NOTE] +> Useful information that users should know, even when skimming content. + +> [!TIP] +> Helpful advice for doing things better or more easily. + +> [!IMPORTANT] +> Key information users need to know to achieve their goal. + +> [!WARNING] +> Urgent info that needs immediate user attention to avoid problems. + +> [!CAUTION] +> Advises about risks or negative outcomes of certain actions. +{{< /code >}} + + +{{% note %}} +This syntax is compatible with the GitHub Alert Markdown extension. +{{% /note %}} + + +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. + +{{< code file=layouts/_default/_markup/render-blockquote.html copy=true >}} +{{ $emojis := dict + "caution" ":exclamation:" + "important" ":information_source:" + "note" ":information_source:" + "tip" ":bulb:" + "warning" ":information_source:" +}} + +{{ if eq .Type "alert" }} +
+

+ {{ transform.Emojify (index $emojis .AlertType) }} + {{ or (i18n .AlertType) (title .AlertType) }} +

+ {{ .Text | safeHTML }} +
+{{ else }} +
+ {{ .Text | safeHTML }} +
+{{ end }} +{{< /code >}} + +To override the label, create these entries in your i18n files: + +{{< code-toggle file=i18n/en.toml >}} +caution = 'Caution' +important = 'Important' +note = 'Note' +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 +layouts/ +└── _default/ + └── _markup/ + ├── render-blockquote-alert.html + └── render-blockquote-regular.html +``` diff --git a/content/en/render-hooks/code-blocks.md b/content/en/render-hooks/code-blocks.md index 0c11c7864..d322cb88d 100755 --- a/content/en/render-hooks/code-blocks.md +++ b/content/en/render-hooks/code-blocks.md @@ -7,8 +7,8 @@ keywords: [] menu: docs: parent: render-hooks - weight: 30 -weight: 30 + weight: 40 +weight: 40 toc: true --- diff --git a/content/en/render-hooks/headings.md b/content/en/render-hooks/headings.md index c48bb11e1..8ae3b808a 100755 --- a/content/en/render-hooks/headings.md +++ b/content/en/render-hooks/headings.md @@ -7,8 +7,8 @@ keywords: [] menu: docs: parent: render-hooks - weight: 40 -weight: 40 + weight: 50 +weight: 50 toc: true --- @@ -24,7 +24,9 @@ Heading render hook templates receive the following [context]: ###### Attributes -(`map`) The Markdown attributes, available if you configure your site as follows: +(`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] diff --git a/content/en/render-hooks/images.md b/content/en/render-hooks/images.md index 2d9b5e2e5..1638ceeae 100755 --- a/content/en/render-hooks/images.md +++ b/content/en/render-hooks/images.md @@ -7,8 +7,8 @@ keywords: [] menu: docs: parent: render-hooks - weight: 50 -weight: 50 + weight: 60 +weight: 60 toc: true --- @@ -32,7 +32,9 @@ Image render hook templates receive the following context: ###### Attributes -(`map`) The Markdown attributes, available if you configure your site as follows: +(`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] diff --git a/content/en/render-hooks/links.md b/content/en/render-hooks/links.md index bf0485068..79c3d6926 100755 --- a/content/en/render-hooks/links.md +++ b/content/en/render-hooks/links.md @@ -7,8 +7,8 @@ keywords: [] menu: docs: parent: render-hooks - weight: 60 -weight: 60 + weight: 70 +weight: 70 toc: true --- From 85a3d9958d0830b099a68ff477c81e534b4c9632 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Mon, 12 Aug 2024 11:05:24 -0700 Subject: [PATCH 05/36] Update theme --- .../gohugoioTheme/layouts/_default/documentation-home.html | 2 +- .../gohugoio/gohugoioTheme/layouts/_default/list.html | 2 +- _vendor/modules.txt | 2 +- go.mod | 2 +- go.sum | 2 ++ 5 files changed, 6 insertions(+), 4 deletions(-) diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/documentation-home.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/documentation-home.html index 91f744c30..f3cf291be 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/documentation-home.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/documentation-home.html @@ -1,4 +1,4 @@ {{ define "main" }} -{{ $section_to_display := (.Site.Taxonomies.categories.fundamentals).Pages | lang.Merge (.Sites.First.Taxonomies.categories.fundamentals).Pages }} +{{ $section_to_display := (.Site.Taxonomies.categories.fundamentals).Pages | lang.Merge (.Sites.Default.Taxonomies.categories.fundamentals).Pages }} {{ partial "pagelayout.html" (dict "context" . "section_to_display" $section_to_display ) }} {{ end }} diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/list.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/list.html index 3b7a2307e..94057aafe 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/list.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/list.html @@ -1,5 +1,5 @@ {{ define "main" }} - {{ $paginator := .Paginate (.Pages | lang.Merge (where .Sites.First.RegularPages "Section" .Section)) }} + {{ $paginator := .Paginate (.Pages | lang.Merge (where .Sites.Default.RegularPages "Section" .Section)) }} {{ $section_to_display := .Sections | default $paginator.Pages }} {{ partial "pagelayout.html" (dict "context" . "section_to_display" $section_to_display ) }} {{ end }} diff --git a/_vendor/modules.txt b/_vendor/modules.txt index 1bde873a0..df5e4aa7a 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1 +1 @@ -# github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472 +# github.com/gohugoio/gohugoioTheme v0.0.0-20240812175901-cc0ef8e4a14a diff --git a/go.mod b/go.mod index 51d5f3a43..f2884c1c8 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/gohugoio/hugoDocs go 1.16 -require github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472 // indirect +require github.com/gohugoio/gohugoioTheme v0.0.0-20240812175901-cc0ef8e4a14a // indirect diff --git a/go.sum b/go.sum index 633446af0..9deb49acd 100644 --- a/go.sum +++ b/go.sum @@ -10,3 +10,5 @@ github.com/gohugoio/gohugoioTheme v0.0.0-20240623150114-cc7096eab3fd h1:I8X7c0oB github.com/gohugoio/gohugoioTheme v0.0.0-20240623150114-cc7096eab3fd/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472 h1:AYZUibKKFRBp2VCQpDHW+JmQKvCvyhX7z7/SOLUSCcw= github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20240812175901-cc0ef8e4a14a h1:E3JbZo69eqFBz6B+meQlKyy/ZBZQ73ldVDw8TADiIrQ= +github.com/gohugoio/gohugoioTheme v0.0.0-20240812175901-cc0ef8e4a14a/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= From bf42bbe6b182422841545f3901d39e88aef09e1c Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Mon, 12 Aug 2024 12:03:05 -0700 Subject: [PATCH 06/36] Update references to render hooks https://gohugo.io/about/features/#content-authoring https://gohugo.io/render-hooks/introduction/ --- content/en/about/features.md | 2 +- content/en/render-hooks/introduction.md | 2 ++ 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/about/features.md b/content/en/about/features.md index cb710aa4b..835384723 100644 --- 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 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, and links. 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/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md index 8268b2ec7..103d9a84e 100755 --- a/content/en/render-hooks/introduction.md +++ b/content/en/render-hooks/introduction.md @@ -13,6 +13,7 @@ weight: 20 When rendering Markdown to HTML, render hooks override the conversion. Each render hook is a template, with one template for each supported element type: +- [Blockquotes](/render-hooks/blockquotes) - [Code blocks](/render-hooks/code-blocks) - [Headings](/render-hooks/headings) - [Images](/render-hooks/images) @@ -54,6 +55,7 @@ Each render hook is a template, with one template for each supported element typ layouts/ └── _default/ └── _markup/ + ├── render-blockquote.html ├── render-codeblock.html ├── render-heading.html ├── render-image.html From e0fa2f0d1dc53e6e9f4ff85018540af68d208a22 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Mon, 12 Aug 2024 12:19:07 -0700 Subject: [PATCH 07/36] Add new-in badge to blockquote render hook page --- content/en/render-hooks/blockquotes.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md index fd9a837d5..5f3974fc9 100755 --- a/content/en/render-hooks/blockquotes.md +++ b/content/en/render-hooks/blockquotes.md @@ -12,6 +12,8 @@ weight: 30 toc: true --- +{{< new-in 0.132.0 >}} + ## Context Blockquote render hook templates receive the following [context]: From 2c137cb48e4b9ddc7483ced488532308d628c79c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Mon, 12 Aug 2024 22:06:12 +0200 Subject: [PATCH 08/36] Update blockquotes.md Add PageInner --- content/en/render-hooks/blockquotes.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/content/en/render-hooks/blockquotes.md b/content/en/render-hooks/blockquotes.md index 5f3974fc9..e0eda5c51 100755 --- a/content/en/render-hooks/blockquotes.md +++ b/content/en/render-hooks/blockquotes.md @@ -43,6 +43,12 @@ block = true (`page`) A reference to the current page. +###### PageInner + +(`page`) A reference to a page nested via the [`RenderShortcodes`] method. + +[`RenderShortcodes`]: /methods/page/rendershortcodes + ###### Position (`string`) The position of the blockquote within the page content. From a7ce9a5e8b29cfe0a024ad3f91cae35d41995922 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Tue, 13 Aug 2024 12:33:04 +0200 Subject: [PATCH 09/36] netlify: Hugo 0.132.1 --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index 42618fbfd..b512c42fb 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ command = "hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.132.0" + HUGO_VERSION = "0.132.1" [context.production.environment] HUGO_ENV = "production" From 2f793d3284c2573107e12583613b5762edc348df Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Mon, 12 Aug 2024 11:01:45 -0700 Subject: [PATCH 10/36] Document passthrough render hooks --- content/en/functions/transform/ToMath.md | 3 - content/en/render-hooks/introduction.md | 1 + content/en/render-hooks/passthrough.md | 125 +++++++++++++++++++++++ 3 files changed, 126 insertions(+), 3 deletions(-) create mode 100755 content/en/render-hooks/passthrough.md diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md index 8ae2f4d33..73c36dd4c 100644 --- a/content/en/functions/transform/ToMath.md +++ b/content/en/functions/transform/ToMath.md @@ -112,6 +112,3 @@ There are 3 ways to handle errors from KaTeX: [options]: #options [error handling]: #error-handling [KaTeX options]: https://katex.org/docs/options.html - - - diff --git a/content/en/render-hooks/introduction.md b/content/en/render-hooks/introduction.md index 103d9a84e..3745fc398 100755 --- a/content/en/render-hooks/introduction.md +++ b/content/en/render-hooks/introduction.md @@ -18,6 +18,7 @@ When rendering Markdown to HTML, render hooks override the conversion. Each rend - [Headings](/render-hooks/headings) - [Images](/render-hooks/images) - [Links](/render-hooks/links) +- [Passthrough elements](/render-hooks/passthrough) {{% note %}} Hugo supports multiple [content formats] including Markdown, HTML, AsciiDoc, Emacs Org Mode, Pandoc, and reStructuredText. diff --git a/content/en/render-hooks/passthrough.md b/content/en/render-hooks/passthrough.md new file mode 100755 index 000000000..3b82116e6 --- /dev/null +++ b/content/en/render-hooks/passthrough.md @@ -0,0 +1,125 @@ +--- +title: Passthrough render hooks +linkTitle: Passthrough +description: Create a passthrough render hook to override the rendering of text snippets captured by the Goldmark passthrough extension. +categories: [render hooks] +keywords: [] +menu: + docs: + parent: render-hooks + weight: 80 +weight: 80 +toc: true +--- + +{{< new-in 0.132.0 >}} + +## Overview + +Hugo uses [Goldmark] to render Markdown to HTML. Goldmark supports custom extensions to extend its core functionality. The Goldmark [passthrough extension] captures and preserves raw Markdown within delimited snippets of text, including the delimiters themselves. These are known as _passthrough elements_. + +[Goldmark]: https://github.com/yuin/goldmark +[passthrough extension]: /getting-started/configuration-markup/#passthrough + +Depending on your choice of delimiters, Hugo will classify a passthrough element as either _block_ or _inline_. Consider this contrived example: + +{{< code file=content/sample.md >}} +This is a + +\[block\] + +passthrough element with opening and closing block delimiters. + +This is an \(inline\) passthrough element with opening and closing inline delimiters. +{{< /code >}} + +Update your site configuration to enable the passthrough extension and define opening and closing delimiters for each passthrough element type, either `block` or `inline`. For example: + +{{< code-toggle file=hugo >}} +[markup.goldmark.extensions.passthrough] +enable = true +[markup.goldmark.extensions.passthrough.delimiters] +block = [['\[', '\]'], ['$$', '$$']] +inline = [['\(', '\)']] +{{< /code-toggle >}} + +In the example above there are two sets of `block` delimiters. You may use either one in your Markdown. + +The Goldmark passthrough extension is often used in conjunction with the MathJax or KaTeX display engine to render [mathematical expressions] written in [LaTeX] or [Tex]. + +[mathematical expressions]: /content-management/mathematics/ +[LaTeX]: https://www.latex-project.org/ +[Tex]: https://en.wikipedia.org/wiki/TeX + +To enable custom rendering of passthrough elements, create a render hook. + +## Context + +Passthrough 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 >}} + +Hugo populates the `Attributes` map for _block_ passthrough elements. Markdown attributes are not applicable to _inline_ elements. + +###### Inner +(`string`) The inner content of the passthrough element, excluding the delimiters. + +###### Ordinal + +(`int`) The zero-based ordinal of the passthrough element 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 passthrough element within the page content. + +###### Type + +(`bool`) The passthrough element type, either `block` or `inline`. + +## Example + +As an alternative to rendering mathematical expressions with the MathJax or KaTeX display engine, create a passthrough render hook which calls the [`transform.ToMath`] function: + +[`transform.ToMath`]: /functions/transform/tomath/ + +{{< code file=layouts/_default/_markup/render-passthrough.html copy=true >}} +{{ if eq .Type "block" }} + {{ $opts := dict "displayMode" true }} + {{ transform.ToMath .Inner $opts }} +{{ else }} + {{ transform.ToMath .Inner }} +{{ end }} +{{< /code >}} + +Although you can use one template with conditional logic as shown above, you can also create separate templates for each [`Type`](#type) of passthrough element: + +```text +layouts/ +└── _default/ + └── _markup/ + ├── render-passthrough-block.html + └── render-passthrough-inline.html +``` + +{{% include "/render-hooks/_common/pageinner.md" %}} From dbe8911ad878acdcb1ee7b3d78b66e29bd99c0a9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Wed, 14 Aug 2024 18:38:14 +0200 Subject: [PATCH 11/36] netlify: Hugo 0.132.2 --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index b512c42fb..ea13529c9 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ command = "hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.132.1" + HUGO_VERSION = "0.132.2" [context.production.environment] HUGO_ENV = "production" From efa7795a046316799d48f2c48279778d6314c98d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Thu, 15 Aug 2024 10:28:00 +0200 Subject: [PATCH 12/36] Update theme --- .../gohugoioTheme/layouts/shortcodes/gomodules-info.html | 3 ++- _vendor/modules.txt | 2 +- go.mod | 2 +- go.sum | 2 ++ 4 files changed, 6 insertions(+), 3 deletions(-) diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html index b56758ac3..31d860394 100644 --- a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html +++ b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html @@ -1,5 +1,6 @@ {{ $text := ` -Most of the commands for **Hugo Modules** require a newer version of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.12 in your Environment settings. +Most of the commands for **Hugo Modules** require a newer version (>= 1.18) of Go installed (see https://golang.org/dl/) and the relevant VCS client (e.g. Git, see https://git-scm.com/downloads/ ). +If you have an "older" site running on Netlify, you may have to set GO_VERSION to 1.19 or newer in your Environment settings. For more information about Go Modules, see: diff --git a/_vendor/modules.txt b/_vendor/modules.txt index df5e4aa7a..492b3e6ac 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1 +1 @@ -# github.com/gohugoio/gohugoioTheme v0.0.0-20240812175901-cc0ef8e4a14a +# github.com/gohugoio/gohugoioTheme v0.0.0-20240815082608-66ccd383a90f diff --git a/go.mod b/go.mod index f2884c1c8..7fd269069 100644 --- a/go.mod +++ b/go.mod @@ -2,4 +2,4 @@ module github.com/gohugoio/hugoDocs go 1.16 -require github.com/gohugoio/gohugoioTheme v0.0.0-20240812175901-cc0ef8e4a14a // indirect +require github.com/gohugoio/gohugoioTheme v0.0.0-20240815082608-66ccd383a90f // indirect diff --git a/go.sum b/go.sum index 9deb49acd..4e5e32477 100644 --- a/go.sum +++ b/go.sum @@ -12,3 +12,5 @@ github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472 h1:AYZUibKK github.com/gohugoio/gohugoioTheme v0.0.0-20240728210410-d42c342ce472/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= github.com/gohugoio/gohugoioTheme v0.0.0-20240812175901-cc0ef8e4a14a h1:E3JbZo69eqFBz6B+meQlKyy/ZBZQ73ldVDw8TADiIrQ= github.com/gohugoio/gohugoioTheme v0.0.0-20240812175901-cc0ef8e4a14a/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= +github.com/gohugoio/gohugoioTheme v0.0.0-20240815082608-66ccd383a90f h1:Eo5z3uUYfmrtIxQvHm388dFOERZwWGTjLuUO6vobzLc= +github.com/gohugoio/gohugoioTheme v0.0.0-20240815082608-66ccd383a90f/go.mod h1:GOYeAPQJ/ok8z7oz1cjfcSlsFpXrmx6VkzQ5RpnyhZM= From eb159fe62bdbe15ef24ac3d458749ec77747c8b2 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 16 Aug 2024 17:04:42 -0700 Subject: [PATCH 13/36] Update menu.md --- content/en/templates/menu.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/templates/menu.md b/content/en/templates/menu.md index de103803c..bd0bc5569 100644 --- a/content/en/templates/menu.md +++ b/content/en/templates/menu.md @@ -129,5 +129,5 @@ Hugo provides two methods to localize your menu entries. See [multilingual]. [localize the menu entries]: /content-management/multilingual/#menus [menu entry defined in front matter]: /content-management/menus/#example-front-matter [menu entry defined in site configuration]: /content-management/menus/#example-site-configuration -[menu and methods]: /methods/menu/ +[menu methods]: /methods/menu/ [multilingual]: /content-management/multilingual/#menus From 9c4697ab323af5cef889ee895820fbef3406c32f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Sat, 17 Aug 2024 22:34:07 +0200 Subject: [PATCH 14/36] netlify: Hugo 0.133.0 --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index ea13529c9..19c4e8a00 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ command = "hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.132.2" + HUGO_VERSION = "0.133.0" [context.production.environment] HUGO_ENV = "production" From 41df916594e99c6217ef98c13ff8f1942249c184 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Wed, 14 Aug 2024 09:02:28 -0700 Subject: [PATCH 15/36] Document the 'else with' construct introduced with Go 1.23 --- content/en/contribute/development.md | 2 +- content/en/functions/go-template/if.md | 2 +- content/en/functions/go-template/with.md | 14 ++++++++++++++ content/en/templates/introduction.md | 14 ++++++++++++++ 4 files changed, 30 insertions(+), 2 deletions(-) diff --git a/content/en/contribute/development.md b/content/en/contribute/development.md index f6ff44ced..e4b183e93 100644 --- a/content/en/contribute/development.md +++ b/content/en/contribute/development.md @@ -48,7 +48,7 @@ For a complete guide to contributing to Hugo, see the [Contribution Guide]. To build the extended edition of Hugo from source you must: 1. Install [Git] -1. Install [Go] version 1.20 or later +1. Install [Go] version 1.23.0 or later 1. Install a C compiler, either [GCC] or [Clang] 1. Update your `PATH` environment variable as described in the [Go documentation] diff --git a/content/en/functions/go-template/if.md b/content/en/functions/go-template/if.md index 19c887f25..9fdf80e99 100644 --- a/content/en/functions/go-template/if.md +++ b/content/en/functions/go-template/if.md @@ -34,7 +34,7 @@ Use with the [`else`] statement: {{ end }} ``` -Use `else if` to check multiple conditions. +Use `else if` to check multiple conditions: ```go-html-template {{ $var := 12 }} diff --git a/content/en/functions/go-template/with.md b/content/en/functions/go-template/with.md index 3a73d54bb..3d628e28d 100644 --- a/content/en/functions/go-template/with.md +++ b/content/en/functions/go-template/with.md @@ -36,6 +36,20 @@ Use with the [`else`] statement: {{ end }} ``` +Use `else with` to check multiple conditions: + +```go-html-template +{{ $v1 := 0 }} +{{ $v2 := 42 }} +{{ with $v1 }} + {{ . }} +{{ else with $v2 }} + {{ . }} → 42 +{{ else }} + {{ print "v1 and v2 are falsy" }} +{{ end }} +``` + Initialize a variable, scoped to the current block: ```go-html-template diff --git a/content/en/templates/introduction.md b/content/en/templates/introduction.md index bb8702717..0a3ff2b0f 100644 --- a/content/en/templates/introduction.md +++ b/content/en/templates/introduction.md @@ -509,6 +509,20 @@ See documentation for [`with`], [`else`], and [`end`]. {{ end }} ``` +To test multiple conditions: + +```go-html-template +{{ $v1 := 0 }} +{{ $v2 := 42 }} +{{ with $v1 }} + {{ . }} +{{ else with $v2 }} + {{ . }} → 42 +{{ else }} + {{ print "v1 and v2 are falsy" }} +{{ end }} +``` + ### Access site parameters See documentation for the [`Params`](/methods/site/params/) method on a `Site` object. From 3ed3673f7d00ef03b3b69a56623b975e71c033f6 Mon Sep 17 00:00:00 2001 From: Andreas Deininger Date: Tue, 20 Aug 2024 22:16:29 +0200 Subject: [PATCH 16/36] Fix typo --- content/en/content-management/content-adapters.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md index ea5ec62ca..4d5bd0890 100644 --- a/content/en/content-management/content-adapters.md +++ b/content/en/content-management/content-adapters.md @@ -125,7 +125,7 @@ Set any [front matter field] in the map passed to the [`AddPage`](#addpage) meth This table describes the fields most commonly passed to the `AddPage` method. -Key|Descripion|Required +Key|Description|Required :--|:--|:-: `content.mediaType`|The content [media type]. Default is `text/markdown`. See [content formats] for examples.|  `content.value`|The content value as a string.|  @@ -148,7 +148,7 @@ When setting the `path`, Hugo transforms the given string to a logical path. For Construct the map passed to the [`AddResource`](#addresource) method using the fields below. -Key|Descripion|Required +Key|Description|Required :--|:--|:-: `content.mediaType`|The content [media type].|:heavy_check_mark: `content.value`|The content value as a string or resource.|:heavy_check_mark: From 205645e9731573e489fcc09a8bcf5bc4e98c7d02 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Wed, 21 Aug 2024 08:47:26 +0200 Subject: [PATCH 17/36] Remove out-dated new-in --- content/en/getting-started/configuration.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 13474c770..6ce10c1c0 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -609,8 +609,6 @@ Setting `force=true` will make a redirect even if there is existing content in t ## 404 server error page {#_404-server-error-page} -{{< new-in 0.103.0 >}} - Hugo will, by default, render all 404 errors when running `hugo server` with the `404.html` template. Note that if you have already added one or more redirects to your [server configuration](#configure-server), you need to add the 404 redirect explicitly, e.g: {{< code-toggle file=config/development/server >}} From f9062042fd7a2e1a5d1303706a1f5f27d8ef6d47 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Wed, 21 Aug 2024 08:54:07 +0200 Subject: [PATCH 18/36] Add the new page config section --- content/en/getting-started/configuration.md | 13 ++++++++++++- 1 file changed, 12 insertions(+), 1 deletion(-) diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 6ce10c1c0..aa2f3ab09 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -378,6 +378,10 @@ Module configuration see [module configuration](/hugo-modules/configuration/). See [custom output formats]. +###### page + +See [Page Configuration](#configure-page). + ###### pagination See [configure pagination](/templates/pagination/#configuration). @@ -496,6 +500,14 @@ enableemoji: true ``` {{% /note %}} +## Configure page + +The `page` configuration section contains [page]-related configuration options. + +{{< code-toggle config=page />}} + +[page]:/methods/page/ + ## Configure build The `build` configuration section contains global build-related configuration options. @@ -922,7 +934,6 @@ output It is recommended to put coarse grained filters (e.g. for language and output format) in the excludes section, e.g.: - {{< code-toggle file=hugo >}} [segments.segment1] [[segments.segment1.excludes]] From fd33370edfd154b25920239a4a2186ca8ced3fc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Wed, 21 Aug 2024 08:57:35 +0200 Subject: [PATCH 19/36] Add new-in 0.133.0 --- content/en/getting-started/configuration.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index aa2f3ab09..924f75f67 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -502,6 +502,8 @@ enableemoji: true ## Configure page +{{< new-in 0.133.0 >}} + The `page` configuration section contains [page]-related configuration options. {{< code-toggle config=page />}} From 05d4fd597262884da22f02f9fdcfac87d227bebf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Wed, 21 Aug 2024 19:37:44 +0200 Subject: [PATCH 20/36] Update PrevInSection.md --- content/en/methods/page/PrevInSection.md | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/content/en/methods/page/PrevInSection.md b/content/en/methods/page/PrevInSection.md index e6daf66c4..b96903b4b 100644 --- a/content/en/methods/page/PrevInSection.md +++ b/content/en/methods/page/PrevInSection.md @@ -53,20 +53,12 @@ Use the opposite label in your navigation links as shown in the example below. {{ end }} ``` -{{% note %}} -The navigation sort order may be different than the page collection sort order. -{{% /note %}} -With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence: - -1. Page [weight] -2. Page [date] (descending) -3. Page [linkTitle], falling back to page [title] -4. Page file path if the page is backed by a file - -For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice. +The `PrevInSection` and `NextInSection` methods uses the default page sort. You can change the sort direction in [Page Config](getting-started/configuration/#configure-page). For more flexibility, use the [Next] and [Prev] methods on the Page object. [date]: /methods/page/date/ [weight]: /methods/page/weight/ [linkTitle]: /methods/page/linktitle/ [title]: /methods/page/title/ +[Next]: /methods/page/next/ +[Prev]: /methods/page/prev/ From 4d419a128ef0b9c8ae18cceb66e35046b5f255d5 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Wed, 21 Aug 2024 12:19:10 -0700 Subject: [PATCH 21/36] Update pagination configuration to use new struct --- hugo.toml | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/hugo.toml b/hugo.toml index 63cc32798..2a271b6e3 100644 --- a/hugo.toml +++ b/hugo.toml @@ -5,7 +5,6 @@ defaultContentLanguage = "en" enableEmoji = true ignoreErrors = ["error-remote-getjson", "error-missing-instagram-accesstoken"] languageCode = "en-us" -paginate = 100 pluralizeListTitles = false timeZone = "Europe/Oslo" title = "Hugo" @@ -13,6 +12,9 @@ title = "Hugo" # We do redirects via Netlify's _redirects file, generated by Hugo (see "outputs" below). disableAliases = true +[pagination] +pagerSize = 100 + [services.googleAnalytics] ID = 'G-MBZGKNMDWC' From e5dee265139b381f163eb648ca46cc860ed09dcc Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Thu, 22 Aug 2024 14:31:18 -0700 Subject: [PATCH 22/36] Update transform.ToMath --- content/en/functions/transform/ToMath.md | 48 ++++++++++++------------ 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/content/en/functions/transform/ToMath.md b/content/en/functions/transform/ToMath.md index 73c36dd4c..db93a7382 100644 --- a/content/en/functions/transform/ToMath.md +++ b/content/en/functions/transform/ToMath.md @@ -27,47 +27,47 @@ EXPRESSION : The math expression to render using KaTeX. OPTIONS -: A map of zero or more [options]. +: A map of zero or more options. ## Options -These are a sub set of the [KaTeX options]. +These are a subset of the [KaTeX options]. output -: String. Default is `mathml`.\ -`html` Outputs HTML only.\ -`mathml`: Outputs MathML only.\ -`htmlAndMathml`: Outputs HTML for visual rendering and MathML for accessibility. +: (`string`). Determines the markup language of the output. One of `html`, `mathml`, or `htmlAndMathml`. Default is `mathml`. + + + + With `html` and `htmlAndMathml` you must include KaTeX CSS within the `head` element of your base template. For example: + + ```html + + ... + + ... + + ``` displayMode -: Boolean. Default is `false`.\ -If `true` the math will be rendered in display mode. If false the math will be rendered in `inline` mode. +: (`bool`) If `true` render in display mode, else render in inline mode. Default is `false`. leqno -: Boolean. Default is `false`.\ -If `true` the math will be rendered with the equation numbers on the left. +: (`bool`) If `true` render with the equation numbers on the left. Default is `false`. fleqn -: Boolean. Default is `false`.\ -If `true`, render flush left with a 2em left margin. +: (`bool`) If `true` render flush left with a 2em left margin. Default is `false`. minRuleThickness -: Float. Default is `0.04`.\ -The minimum thickness of the fraction lines in `em`. +: (`float`) The minimum thickness of the fraction lines in `em`. Default is `0.04`. macros -: Map. Default is `{}`.\ -A map of macros to be used in the math expression. +: (`map`) A map of macros to be used in the math expression. Default is `{}`. throwOnError -: Boolean. Default is `true`.\ -If `true`, KaTeX will throw a `ParseError` when it encounters an unsupported command or invalid LaTex. See [error handling]. +: (`bool`) If `true` throw a `ParseError` when KaTeX encounters an unsupported command or invalid LaTex. See [error handling]. Default is `true`. errorColor -: String. Default is `#cc0000`.\ -The color of the error messages.\ -A color string given in the format "#XXX" or "#XXXXXX" - +: (`string`) The color of the error messages expressed as an RGB [hexadecimal color]. Default is `#cc0000`. ## Examples @@ -107,8 +107,6 @@ There are 3 ways to handle errors from KaTeX: {{- /* chomp trailing newline */ -}} {{< /code >}} - - -[options]: #options [error handling]: #error-handling [KaTeX options]: https://katex.org/docs/options.html +[hexadecimal color]: https://developer.mozilla.org/en-US/docs/Web/CSS/hex-color From cf8dd703400ca013e84ee5012229d91b8f932d26 Mon Sep 17 00:00:00 2001 From: "Hidenori \"Hide\" Matsuki" Date: Fri, 23 Aug 2024 09:51:23 +0900 Subject: [PATCH 23/36] Improve embedded.md Co-authored-by: Joe Mooring --- content/en/templates/embedded.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/content/en/templates/embedded.md b/content/en/templates/embedded.md index 5fbbb8d96..888f4f342 100644 --- a/content/en/templates/embedded.md +++ b/content/en/templates/embedded.md @@ -135,7 +135,7 @@ tags = [] Hugo uses the page title and description for the title and description metadata. The first 6 URLs from the `images` array are used for image metadata. -If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*` or `*cover*,*thumbnail*` are used for image metadata. +If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. Various optional metadata can also be set: @@ -203,7 +203,7 @@ description = "Text about this post" images = ["post-cover.png"] {{}} -If `images` aren't specified in the page front-matter, then hugo searches for [image page resources](/content-management/image-processing/) with `feature`, `cover`, or `thumbnail` in their name. +If [page bundles](/content-management/page-bundles/) are used and the `images` array is empty or undefined, images with file names matching `*feature*`, `*cover*`, or `*thumbnail*` are used for image metadata. If no image resources with those names are found, the images defined in the [site config](/getting-started/configuration/) are used instead. If no images are found at all, then an image-less Twitter `summary` card is used instead of `summary_large_image`. From b5505d22afa1c356dd10c225520a52bd700f6a28 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 23 Aug 2024 07:04:17 -0700 Subject: [PATCH 24/36] Clarify template lookup order for shortcodes --- content/en/templates/shortcode.md | 25 +++++++++++++++++++++---- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/content/en/templates/shortcode.md b/content/en/templates/shortcode.md index 6d9234f71..5587c7479 100644 --- a/content/en/templates/shortcode.md +++ b/content/en/templates/shortcode.md @@ -37,12 +37,29 @@ You can organize your shortcodes in subdirectories, e.g. in `layouts/shortcodes/ Note the forward slash. -### Shortcode template lookup order +### Template lookup order -Shortcode templates have a simple [lookup order]: +Hugo selects shortcode templates based on the shortcode name, the current output format, and the current language. The examples below are sorted by specificity in descending order. The least specific path is at the bottom of the list. -1. `/layouts/shortcodes/.html` -2. `/themes//layouts/shortcodes/.html` +Shortcode name|Output format|Language|Template path +:--|:--|:--|:-- +foo|html|en|layouts/shortcodes/foo.en.html +foo|html|en|layouts/shortcodes/foo.html.html +foo|html|en|layouts/shortcodes/foo.html +foo|html|en|layouts/shortcodes/foo.html.en.html + +Shortcode name|Output format|Language|Template path +:--|:--|:--|:-- +foo|rss|en|layouts/shortcodes/foo.en.xml +foo|rss|en|layouts/shortcodes/foo.rss.xml +foo|rss|en|layouts/shortcodes/foo.en.html +foo|rss|en|layouts/shortcodes/foo.rss.en.xml +foo|rss|en|layouts/shortcodes/foo.xml +foo|rss|en|layouts/shortcodes/foo.html.en.html +foo|rss|en|layouts/shortcodes/foo.html.html +foo|rss|en|layouts/shortcodes/foo.html + +Note that templates provided by a theme or module always take precedence. ### Positional vs. named arguments From bdf3ffc73f77910165ba0f3d7e3f6d4e4e9c2d69 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 23 Aug 2024 07:05:33 -0700 Subject: [PATCH 25/36] Clarify the various next/prev methods --- content/en/getting-started/configuration.md | 40 +++++++++- content/en/methods/_common/_index.md | 13 ---- ...next-prev-on-page-vs-next-prev-on-pages.md | 37 --------- content/en/methods/page/Next.md | 40 +--------- content/en/methods/page/NextInSection.md | 60 +------------- content/en/methods/page/Prev.md | 44 +---------- content/en/methods/page/PrevInSection.md | 53 +------------ .../en/methods/page/_common/next-and-prev.md | 60 ++++++++++++++ .../nextinsection-and-previnsection.md | 78 +++++++++++++++++++ content/en/methods/pages/Next.md | 44 +---------- content/en/methods/pages/Prev.md | 44 +---------- .../en/methods/pages/_common/next-and-prev.md | 72 +++++++++++++++++ 12 files changed, 263 insertions(+), 322 deletions(-) delete mode 100644 content/en/methods/_common/_index.md delete mode 100644 content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md create mode 100644 content/en/methods/page/_common/next-and-prev.md create mode 100644 content/en/methods/page/_common/nextinsection-and-previnsection.md create mode 100644 content/en/methods/pages/_common/next-and-prev.md diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index 924f75f67..b0a6cae66 100644 --- a/content/en/getting-started/configuration.md +++ b/content/en/getting-started/configuration.md @@ -380,7 +380,7 @@ See [custom output formats]. ###### page -See [Page Configuration](#configure-page). +See [configure page](#configure-page). ###### pagination @@ -504,11 +504,45 @@ enableemoji: true {{< new-in 0.133.0 >}} -The `page` configuration section contains [page]-related configuration options. +These methods on a `Page` object navigate to the next or previous page within a page collection, relative to the current page: + +- [Next](/methods/page/next/) +- [NextInSection](/methods/page/nextinsection/) +- [Prev](/methods/page/prev/) +- [PrevInSection](/methods/page/previnsection/) + +Hugo determines the _next_ and _previous_ page by sorting a page collection according to this sorting hierarchy: + +Field|Precedence|Sort direction +:--|:--|:-- +[`weight`]|1|descending +[`date`]|2|descending +[`linkTitle`]|3|descending +[`path`]|4|descending + +[`date`]: /methods/page/date/ +[`weight`]: /methods/page/weight/ +[`linkTitle`]: /methods/page/linktitle/ +[`path`]: /methods/page/path/ + +The sort direction in the table above corresponds to these default site configuration values: {{< code-toggle config=page />}} -[page]:/methods/page/ +To sort all fields in ascending order: + +{{< code-toggle file=hugo >}} +[page] + nextPrevInSectionSortOrder = 'asc' + nextPrevSortOrder = 'asc' +{{< /code-toggle >}} + +{{% note %}} +These settings do not apply to the [`Next`] or [`Prev`] methods on a `Pages` object. + +[`Next`]: /methods/pages/next +[`Prev`]: /methods/pages/next +{{% /note %}} ## Configure build diff --git a/content/en/methods/_common/_index.md b/content/en/methods/_common/_index.md deleted file mode 100644 index 4328d4d14..000000000 --- a/content/en/methods/_common/_index.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -cascade: - _build: - list: never - publishResources: false - render: never ---- - - diff --git a/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md b/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md deleted file mode 100644 index f65037878..000000000 --- a/content/en/methods/_common/next-prev-on-page-vs-next-prev-on-pages.md +++ /dev/null @@ -1,37 +0,0 @@ ---- -# Do not remove front matter. ---- - -The `Next` and `Prev` methods on a `Pages` object are more flexible than the `Next` and `Prev` methods on a `Page` object. - -||Page collection|Custom sort order -:--|:--|:-: -[`PAGES.Next`] and [`PAGES.Prev`]|locally defined|✔️ -[`PAGE.Next`] and [`PAGE.Prev`]|globally defined|❌ - -[`PAGES.Next`]: /methods/pages/next/ -[`PAGES.Prev`]: /methods/pages/prev/ -[`PAGE.Next`]: /methods/page/next/ -[`PAGE.Prev`]: /methods/page/prev/ - -locally defined -: Build the page collection every time you call `PAGES.Next` and `PAGES.Prev`. Navigation between pages is relative to the current page's position within the local collection, independent of the global collection. - -With a local collection, the navigation sort order is the same as the collection sort order. - -globally defined -: Build the page collection once, on a list page. Navigation between pages is relative to the current page's position within the global collection. - -With a global collection, the navigation sort order is fixed, using Hugo's default sort order. In order of precedence: - -1. Page [weight] -2. Page [date] (descending) -3. Page [linkTitle], falling back to page [title] -4. Page file path if the page is backed by a file - -For example, with a global collection sorted by title, the navigation sort order will use Hugo's default sort order. This is probably not what you want or expect. For this reason, the `Next` and `Prev` methods on a `Pages` object are generally a better choice. - -[date]: /methods/page/date/ -[weight]: /methods/page/weight/ -[linkTitle]: /methods/page/linktitle/ -[title]: /methods/page/title/ diff --git a/content/en/methods/page/Next.md b/content/en/methods/page/Next.md index 57fc1f2f8..ff0525700 100644 --- a/content/en/methods/page/Next.md +++ b/content/en/methods/page/Next.md @@ -1,6 +1,6 @@ --- title: Next -description: Returns the next page in a global page collection, relative to the given page. +description: Returns the next page in a site's collection of regular pages, relative to the current page. categories: [] keywords: [] action: @@ -12,42 +12,6 @@ action: - methods/pages/Prev returnType: page.Page signatures: [PAGE.Next] -toc: true --- -The behavior of the `Prev` and `Next` methods on a `Page` object is probably the reverse of what you expect. - -With this content structure: - -```text -content/ -├── pages/ -│ ├── _index.md -│ ├── page-1.md <-- front matter: weight = 10 -│ ├── page-2.md <-- front matter: weight = 20 -│ └── page-3.md <-- front matter: weight = 30 -└── _index.md -``` - -When you visit page-2: - -- The `Prev` method points to page-3 -- The `Next` method points to page-1 - -{{% note %}} -Use the opposite label in your navigation links as shown in the example below. -{{% /note %}} - -```go-html-template -{{ with .Next }} - Prev -{{ end }} - -{{ with .Prev }} - Next -{{ end }} -``` - -## Compare to Pages methods - -{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} +{{% include "methods/page/_common/next-and-prev.md" %}} diff --git a/content/en/methods/page/NextInSection.md b/content/en/methods/page/NextInSection.md index 59a35d03d..640e9b44a 100644 --- a/content/en/methods/page/NextInSection.md +++ b/content/en/methods/page/NextInSection.md @@ -1,71 +1,15 @@ --- title: NextInSection -description: Returns the next page within a section, relative to the given page. +description: Returns the next regular page in a section, relative to the given page. categories: [] keywords: [] action: related: - methods/page/PrevInSection - - methods/page/Next - - methods/page/Prev - methods/pages/Next - methods/pages/Prev returnType: page.Page signatures: [PAGE.NextInSection] --- -The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect. - -With this content structure: - -```text -content/ -├── books/ -│ ├── _index.md -│ ├── book-1.md -│ ├── book-2.md -│ └── book-3.md -├── films/ -│ ├── _index.md -│ ├── film-1.md -│ ├── film-2.md -│ └── film-3.md -└── _index.md -``` - -When you visit book-2: - -- The `PrevInSection` method points to book-3 -- The `NextInSection` method points to book-1 - -{{% note %}} -Use the opposite label in your navigation links as shown in the example below. -{{% /note %}} - -```go-html-template -{{ with .NextInSection }} - Previous in section -{{ end }} - -{{ with .PrevInSection }} - Next in section -{{ end }} -``` - -{{% note %}} -The navigation sort order may be different than the page collection sort order. -{{% /note %}} - -With the `PrevInSection` and `NextInSection` methods, the navigation sort order is fixed, using Hugo’s default sort order. In order of precedence: - -1. Page [weight] -2. Page [date] (descending) -3. Page [linkTitle], falling back to page [title] -4. Page file path if the page is backed by a file - -For example, with a page collection sorted by title, the navigation sort order will use Hugo’s default sort order. This is probably not what you want or expect. For this reason, the Next and Prev methods on a Pages object are generally a better choice. - -[date]: /methods/page/date/ -[weight]: /methods/page/weight/ -[linkTitle]: /methods/page/linktitle/ -[title]: /methods/page/title/ +{{% include "methods/page/_common/nextinsection-and-previnsection.md" %}} diff --git a/content/en/methods/page/Prev.md b/content/en/methods/page/Prev.md index b1a503af5..d28b50265 100644 --- a/content/en/methods/page/Prev.md +++ b/content/en/methods/page/Prev.md @@ -1,53 +1,17 @@ --- title: Prev -description: Returns the previous page in a global page collection, relative to the given page. +description: Returns the previous page in a site's collection of regular pages, relative to the current page. categories: [] keywords: [] action: related: - methods/page/Next - - methods/page/PrevInSection - methods/page/NextInSection - - methods/pages/Prev + - methods/page/PrevInSection - methods/pages/Next + - methods/pages/Prev returnType: page.Page signatures: [PAGE.Prev] -toc: true --- -The behavior of the `Prev` and `Next` methods on a `Page` object is probably the reverse of what you expect. - -With this content structure: - -```text -content/ -├── pages/ -│ ├── _index.md -│ ├── page-1.md <-- front matter: weight = 10 -│ ├── page-2.md <-- front matter: weight = 20 -│ └── page-3.md <-- front matter: weight = 30 -└── _index.md -``` - -When you visit page-2: - -- The `Prev` method points to page-3 -- The `Next` method points to page-1 - -{{% note %}} -Use the opposite label in your navigation links as shown in the example below. -{{% /note %}} - -```go-html-template -{{ with .Next }} - Prev -{{ end }} - -{{ with .Prev }} - Next -{{ end }} -``` - -## Compare to Pages methods - -{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} +{{% include "methods/page/_common/next-and-prev.md" %}} diff --git a/content/en/methods/page/PrevInSection.md b/content/en/methods/page/PrevInSection.md index b96903b4b..aaafb367e 100644 --- a/content/en/methods/page/PrevInSection.md +++ b/content/en/methods/page/PrevInSection.md @@ -1,64 +1,15 @@ --- title: PrevInSection -description: Returns the previous page within a section, relative to the given page. +description: Returns the previous regular page in a section, relative to the given page. categories: [] keywords: [] action: related: - methods/page/NextInSection - - methods/page/Next - methods/pages/Next - - methods/page/Prev - methods/pages/Prev returnType: page.Page signatures: [PAGE.PrevInSection] --- - -The behavior of the `PrevInSection` and `NextInSection` methods on a `Page` object is probably the reverse of what you expect. - -With this content structure: - -```text -content/ -├── books/ -│ ├── _index.md -│ ├── book-1.md -│ ├── book-2.md -│ └── book-3.md -├── films/ -│ ├── _index.md -│ ├── film-1.md -│ ├── film-2.md -│ └── film-3.md -└── _index.md -``` - -When you visit book-2: - -- The `PrevInSection` method points to book-3 -- The `NextInSection` method points to book-1 - -{{% note %}} -Use the opposite label in your navigation links as shown in the example below. -{{% /note %}} - -```go-html-template -{{ with .NextInSection }} - Previous in section -{{ end }} - -{{ with .PrevInSection }} - Next in section -{{ end }} -``` - - -The `PrevInSection` and `NextInSection` methods uses the default page sort. You can change the sort direction in [Page Config](getting-started/configuration/#configure-page). For more flexibility, use the [Next] and [Prev] methods on the Page object. - -[date]: /methods/page/date/ -[weight]: /methods/page/weight/ -[linkTitle]: /methods/page/linktitle/ -[title]: /methods/page/title/ -[Next]: /methods/page/next/ -[Prev]: /methods/page/prev/ +{{% include "methods/page/_common/nextinsection-and-previnsection.md" %}} diff --git a/content/en/methods/page/_common/next-and-prev.md b/content/en/methods/page/_common/next-and-prev.md new file mode 100644 index 000000000..252e1ad9b --- /dev/null +++ b/content/en/methods/page/_common/next-and-prev.md @@ -0,0 +1,60 @@ +--- +# Do not remove front matter. +--- + +Hugo determines the _next_ and _previous_ page by sorting the site's collection of regular pages according to this sorting hierarchy: + +Field|Precedence|Sort direction +:--|:--|:-- +[`weight`]|1|descending +[`date`]|2|descending +[`linkTitle`]|3|descending +[`path`]|4|descending + +[`date`]: /methods/page/date/ +[`weight`]: /methods/page/weight/ +[`linkTitle`]: /methods/page/linktitle/ +[`path`]: /methods/page/path/ + +The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. + +For example, with this content structure: + +```text +content/ +├── pages/ +│ ├── _index.md +│ ├── page-1.md <-- front matter: weight = 10 +│ ├── page-2.md <-- front matter: weight = 20 +│ └── page-3.md <-- front matter: weight = 30 +└── _index.md +``` + +And these templates: + +{{< code file=layouts/_default/list.html >}} +{{ range .Pages.ByWeight}} +

{{ .LinkTitle }}

+{{ end }} +{{< /code >}} + +{{< code file=layouts/_default/single.html >}} +{{ with .Prev }} + Previous +{{ end }} + +{{ with .Next }} + Next +{{ end }} +{{< /code >}} + +When you visit page-2: + +- The `Prev` method points to page-3 +- The `Next` method points to page-1 + +To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. + +[site configuration]: getting-started/configuration/#configure-page +[`Next`]: /methods/pages/prev +[`Prev`]: /methods/pages/prev diff --git a/content/en/methods/page/_common/nextinsection-and-previnsection.md b/content/en/methods/page/_common/nextinsection-and-previnsection.md new file mode 100644 index 000000000..aed9a310f --- /dev/null +++ b/content/en/methods/page/_common/nextinsection-and-previnsection.md @@ -0,0 +1,78 @@ +--- +# Do not remove front matter. +--- + +Hugo determines the _next_ and _previous_ page by sorting the current section's regular pages according to this sorting hierarchy: + +Field|Precedence|Sort direction +:--|:--|:-- +[`weight`]|1|descending +[`date`]|2|descending +[`linkTitle`]|3|descending +[`path`]|4|descending + +[`date`]: /methods/page/date/ +[`weight`]: /methods/page/weight/ +[`linkTitle`]: /methods/page/linktitle/ +[`path`]: /methods/page/path/ + +The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. + +For example, with this content structure: + +```text +content/ +├── pages/ +│ ├── _index.md +│ ├── page-1.md <-- front matter: weight = 10 +│ ├── page-2.md <-- front matter: weight = 20 +│ └── page-3.md <-- front matter: weight = 30 +└── _index.md +``` + +And these templates: + +{{< code file=layouts/_default/list.html >}} +{{ range .Pages.ByWeight}} +

{{ .LinkTitle }}

+{{ end }} +{{< /code >}} + +{{< code file=layouts/_default/single.html >}} +{{ with .PrevInSection }} + Previous +{{ end }} + +{{ with .NextInSection }} + Next +{{ end }} +{{< /code >}} + +When you visit page-2: + +- The `PrevInSection` method points to page-3 +- The `NextInSection` method points to page-1 + +To reverse the meaning of _next_ and _previous_ you can change the sort direction in your [site configuration], or use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. + +[site configuration]: getting-started/configuration/#configure-page +[`Next`]: /methods/pages/prev +[`Prev`]: /methods/pages/prev + +## Example + +Code defensively by checking for page existence: + +```go-html-template +{{ with .PrevInSection }} + Previous +{{ end }} + +{{ with .NextInSection }} + Next +{{ end }} +``` + +## Alternative + +Use the [`Next`] and [`Prev`] methods on a `Pages` object for more flexibility. diff --git a/content/en/methods/pages/Next.md b/content/en/methods/pages/Next.md index b7284609f..dcf1231ac 100644 --- a/content/en/methods/pages/Next.md +++ b/content/en/methods/pages/Next.md @@ -1,55 +1,17 @@ --- title: Next -description: Returns the next page in a local page collection, relative to the given page. +description: Returns the next page in a page collection, relative to the given page. categories: [] keywords: [] action: related: - methods/pages/Prev - methods/page/Next - - methods/page/NextInSection - methods/page/Prev + - methods/page/NextInSection - methods/page/PrevInSection returnType: page.Page signatures: [PAGES.Next PAGE] -toc: true --- -The behavior of the `Prev` and `Next` methods on a `Pages` objects is probably the reverse of what you expect. - -With this content structure and the page collection sorted by weight in ascending order: - -```text -content/ -├── pages/ -│ ├── _index.md -│ ├── page-1.md <-- front matter: weight = 10 -│ ├── page-2.md <-- front matter: weight = 20 -│ └── page-3.md <-- front matter: weight = 30 -└── _index.md -``` - -When you visit page-2: - -- The `Prev` method points to page-3 -- The `Next` method points to page-1 - -{{% note %}} -Use the opposite label in your navigation links as shown in the example below. -{{% /note %}} - -```go-html-template -{{ $pages := where .Site.RegularPages.ByWeight "Section" "pages" }} - -{{ with $pages.Next . }} - Previous -{{ end }} - -{{ with $pages.Prev . }} - Next -{{ end }} -``` - -## Compare to Page methods - -{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} +{{% include "methods/pages/_common/next-and-prev.md" %}} diff --git a/content/en/methods/pages/Prev.md b/content/en/methods/pages/Prev.md index b9ef27a45..2d8738521 100644 --- a/content/en/methods/pages/Prev.md +++ b/content/en/methods/pages/Prev.md @@ -1,55 +1,17 @@ --- title: Prev -description: Returns the previous page in a local page collection, relative to the given page. +description: Returns the previous page in a page collection, relative to the given page. categories: [] keywords: [] action: related: - methods/pages/Next - methods/page/Next - - methods/page/NextInSection - methods/page/Prev + - methods/page/NextInSection - methods/page/PrevInSection returnType: page.Pages signatures: [PAGES.Prev PAGE] -toc: true --- -The behavior of the `Prev` and `Next` methods on a `Pages` objects is probably the reverse of what you expect. - -With this content structure and the page collection sorted by weight in ascending order: - -```text -content/ -├── pages/ -│ ├── _index.md -│ ├── page-1.md <-- front matter: weight = 10 -│ ├── page-2.md <-- front matter: weight = 20 -│ └── page-3.md <-- front matter: weight = 30 -└── _index.md -``` - -When you visit page-2: - -- The `Prev` method points to page-3 -- The `Next` method points to page-1 - -{{% note %}} -Use the opposite label in your navigation links as shown in the example below. -{{% /note %}} - -```go-html-template -{{ $pages := where .Site.RegularPages.ByWeight "Section" "pages" }} - -{{ with $pages.Next . }} - Previous -{{ end }} - -{{ with $pages.Prev . }} - Next -{{ end }} -``` - -## Compare to Page methods - -{{% include "methods/_common/next-prev-on-page-vs-next-prev-on-pages.md" %}} +{{% include "methods/pages/_common/next-and-prev.md" %}} diff --git a/content/en/methods/pages/_common/next-and-prev.md b/content/en/methods/pages/_common/next-and-prev.md new file mode 100644 index 000000000..e0d05de84 --- /dev/null +++ b/content/en/methods/pages/_common/next-and-prev.md @@ -0,0 +1,72 @@ +--- +# Do not remove front matter. +--- + +Hugo determines the _next_ and _previous_ page by sorting the page collection according to this sorting hierarchy: + +Field|Precedence|Sort direction +:--|:--|:-- +[`weight`]|1|descending +[`date`]|2|descending +[`linkTitle`]|3|descending +[`path`]|4|descending + +[`date`]: /methods/page/date/ +[`weight`]: /methods/page/weight/ +[`linkTitle`]: /methods/page/linktitle/ +[`path`]: /methods/page/path/ + +The sorted page collection used to determine the _next_ and _previous_ page is independent of other page collections, which may lead to unexpected behavior. + +For example, with this content structure: + +```text +content/ +├── pages/ +│ ├── _index.md +│ ├── page-1.md <-- front matter: weight = 10 +│ ├── page-2.md <-- front matter: weight = 20 +│ └── page-3.md <-- front matter: weight = 30 +└── _index.md +``` + +And these templates: + +{{< code file=layouts/_default/list.html >}} +{{ range .Pages.ByWeight}} +

{{ .LinkTitle }}

+{{ end }} +{{< /code >}} + +{{< code file=layouts/_default/single.html >}} +{{ $pages := .CurrentSection.Pages.ByWeight }} + +{{ with $pages.Prev . }} + Previous +{{ end }} + +{{ with $pages.Next . }} + Next +{{ end }} +{{< /code >}} + +When you visit page-2: + +- The `Prev` method points to page-3 +- The `Next` method points to page-1 + +To reverse the meaning of _next_ and _previous_ you can chain the [`Reverse`] method to the page collection definition: + +{{< code file=layouts/_default/single.html >}} +{{ $pages := .CurrentSection.Pages.ByWeight.Reverse }} + +{{ with $pages.Prev . }} + Previous +{{ end }} + +{{ with $pages.Next . }} + Next +{{ end }} +{{< /code >}} + +[`Reverse`]: /methods/pages/reverse/ From e5681ad01e1ae3cac32077f0b2801d49dbdff4a4 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 23 Aug 2024 07:19:02 -0700 Subject: [PATCH 26/36] Improve formatting of example code --- content/en/methods/page/_common/next-and-prev.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/methods/page/_common/next-and-prev.md b/content/en/methods/page/_common/next-and-prev.md index 252e1ad9b..0d1436e11 100644 --- a/content/en/methods/page/_common/next-and-prev.md +++ b/content/en/methods/page/_common/next-and-prev.md @@ -33,7 +33,7 @@ content/ And these templates: {{< code file=layouts/_default/list.html >}} -{{ range .Pages.ByWeight}} +{{ range .Pages.ByWeight }}

{{ .LinkTitle }}

{{ end }} {{< /code >}} From ec52c7ba10e946c4c68ac1185789e0b79eb73ed0 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Fri, 23 Aug 2024 07:19:38 -0700 Subject: [PATCH 27/36] Improve formatting of example code --- .../en/methods/page/_common/nextinsection-and-previnsection.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/methods/page/_common/nextinsection-and-previnsection.md b/content/en/methods/page/_common/nextinsection-and-previnsection.md index aed9a310f..6c558b69e 100644 --- a/content/en/methods/page/_common/nextinsection-and-previnsection.md +++ b/content/en/methods/page/_common/nextinsection-and-previnsection.md @@ -33,7 +33,7 @@ content/ And these templates: {{< code file=layouts/_default/list.html >}} -{{ range .Pages.ByWeight}} +{{ range .Pages.ByWeight }}

{{ .LinkTitle }}

{{ end }} {{< /code >}} From 60f6cb63bd7447e3af61301b68ef96a43a63671d Mon Sep 17 00:00:00 2001 From: Ashish Bhatia Date: Sat, 24 Aug 2024 07:17:21 -0700 Subject: [PATCH 28/36] Update migrations.md Co-authored-by: Joe Mooring --- content/en/tools/migrations.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/content/en/tools/migrations.md b/content/en/tools/migrations.md index 3a2cdac35..99064e271 100644 --- a/content/en/tools/migrations.md +++ b/content/en/tools/migrations.md @@ -13,9 +13,9 @@ toc: true aliases: [/developer-tools/migrations/, /developer-tools/migrated/] --- -This section highlights some projects around Hugo that are independently developed. These tools try to extend the functionality of our static site generator or help you to get started. +This section highlights some independently developed projects related to Hugo. These tools extend functionality or help you to get started. -Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll take care to export your content into Hugo-friendly formats. +Take a look at this list of migration tools if you currently use other blogging tools like Jekyll or WordPress but intend to switch to Hugo instead. They'll help you export your content into Hugo-friendly formats. ## Jekyll @@ -35,18 +35,18 @@ Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jek ## DokuWiki [dokuwiki-to-hugo](https://github.com/wgroeneveld/dokuwiki-to-hugo) -: Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extra's like the TODO plugin. Written with extensibility in mind using python 3. Also generates a TOML header for each page. Designed to copypaste the wiki directory into your /content directory. +: Migrates your DokuWiki source pages from [DokuWiki syntax](https://www.dokuwiki.org/wiki:syntax) to Hugo Markdown syntax. Includes extras like the TODO plugin. Written with extensibility in mind using Python 3. Also generates a TOML header for each page. Designed to copy-paste the wiki directory into your /content directory. ## WordPress [wordpress-to-hugo-exporter](https://github.com/SchumacherFM/wordpress-to-hugo-exporter) -: A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built in Jekyll converter listed above.) +: A one-click WordPress plugin that converts all posts, pages, taxonomies, metadata, and settings to Markdown and YAML which can be dropped into Hugo. (Note: If you have trouble using this plugin, you can [export your site for Jekyll](https://wordpress.org/plugins/jekyll-exporter/) and use Hugo's built-in Jekyll converter listed above.) [blog2md](https://github.com/palaniraja/blog2md) : Works with [exported xml](https://en.support.wordpress.com/export/) file of your free YOUR-TLD.wordpress.com website. It also saves approved comments to `YOUR-POST-NAME-comments.md` file along with posts. [wordhugopress](https://github.com/nantipov/wordhugopress) -: A small utility written in Java, exports the entire WordPress site from the database and resource (e.g. images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging of the multiple WordPress sites into a single Hugo one. +: A small utility written in Java that exports the entire WordPress site from the database and resource (e.g., images) files stored locally or remotely. Therefore, migration from the backup files is possible. Supports merging multiple WordPress sites into a single Hugo site. [wp2hugo](https://github.com/ashishb/wp2hugo) : A Go-based CLI tool to migrate WordPress website to Hugo while preserving original URLs, GUIDs (for feeds), image URLs, code highlights, table of contents, YouTube embeds, Google Maps embeds, and original WordPress navigation categories. @@ -57,7 +57,7 @@ Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jek : A simple Medium to Hugo exporter able to import stories in one command, including front matter. [medium-to-hugo](https://github.com/bgadrian/medium-to-hugo) -: CLI tool written in Go to export medium posts into a Hugo compatible Markdown format. Tags and images are included. All images will be downloaded locally and linked appropriately. +: A CLI tool written in Go to export medium posts into a Hugo-compatible Markdown format. Tags and images are included. All images will be downloaded locally and linked appropriately. ## Tumblr @@ -68,7 +68,7 @@ Alternatively, you can use the [Jekyll import command](/commands/hugo_import_jek : Export all your Tumblr content to Hugo Markdown files with preserved original formatting. [Tumblr to Hugo](https://github.com/jipiboily/tumblr-to-hugo) -: A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. Furthermore, "Tumblr to Hugo" creates a CSV file with the original URL and the new path on Hugo, to help you setup the redirections. +: A migration tool that converts each of your Tumblr posts to a content file with a proper title and path. It also generates a CSV file to help you set up URL redirects. ## Drupal From b0e5ab0514898fe945f3223035862d84dde18c64 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sat, 24 Aug 2024 10:15:35 -0700 Subject: [PATCH 29/36] Fir typo --- content/en/getting-started/configuration-markup.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index 4ba4a60fe..6dabd7b23 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -238,7 +238,7 @@ This is the default configuration for the AsciiDoc renderer: ###### attributes -(`map`) A map of key-value pairs, each a document attributes,See Asciidoctor’s [attributes]. +(`map`) A map of key-value pairs, each a document attributes. See Asciidoctor’s [attributes]. [attributes]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions From c3350f4cfd7b853b577cd6b6aa8b947caa63f26f Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sun, 25 Aug 2024 08:32:29 -0700 Subject: [PATCH 30/36] Update definition of falsy to include zero time.Time values --- content/en/functions/go-template/_common/truthy-falsy.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/content/en/functions/go-template/_common/truthy-falsy.md b/content/en/functions/go-template/_common/truthy-falsy.md index c8fc9e09e..c41bb6561 100644 --- a/content/en/functions/go-template/_common/truthy-falsy.md +++ b/content/en/functions/go-template/_common/truthy-falsy.md @@ -2,4 +2,6 @@ # Do not remove front matter. --- -In Go templates, the falsy values are `false`, `0`, any nil pointer or interface value, and any array, slice, map, or string of length zero. Everything else is truthy. +The falsy values are `false`, `0`, any `nil` pointer or interface value, any array, slice, map, or string of length zero, and zero `time.Time` values. + +Everything else is truthy. From ca802fbec1f058cfdbbbc18727042036686b17d9 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sun, 25 Aug 2024 09:03:24 -0700 Subject: [PATCH 31/36] Document how to enable AsciiDoc syntax highlighting --- .../getting-started/configuration-markup.md | 45 +++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/content/en/getting-started/configuration-markup.md b/content/en/getting-started/configuration-markup.md index 6dabd7b23..0046ff1ed 100644 --- a/content/en/getting-started/configuration-markup.md +++ b/content/en/getting-started/configuration-markup.md @@ -302,6 +302,51 @@ To mitigate security risks, entries in the extension array may not contain forwa my-attribute-name = "my value" {{< /code-toggle >}} +### AsciiDoc syntax highlighting + +Follow the steps below to enable syntax highlighting. + +Step 1 +: Set the `source-highlighter` attribute in your site configuration. For example: + +{{< code-toggle file=hugo >}} +[markup.asciidocExt.attributes] +source-highlighter = 'rouge' +{{< /code-toggle >}} + +Step 2 +: Generate the highlighter CSS. For example: + +```text +rougify style monokai.sublime > assets/css/syntax.css +``` + +Step 3 +: In your base template add a link to the CSS file: + +{{< code file=layouts/_default/baseof.html >}} + + ... + {{ with resources.Get "css/syntax.css" }} + + {{ end }} + ... + +{{< /code >}} + +Then add the code to be highlighted to your markup: + +```text +[#hello,ruby] +---- +require 'sinatra' + +get '/hi' do + "Hello World!" +end +---- +``` + ### AsciiDoc troubleshooting Run `hugo --logLevel debug` to examine Hugo's call to the Asciidoctor executable: From 7c766e724e8cb16c424d3896c88a980dd93fe4e4 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sun, 25 Aug 2024 12:30:08 -0700 Subject: [PATCH 32/36] Update page resources documentation --- .../en/content-management/page-resources.md | 127 +++++++++--------- 1 file changed, 64 insertions(+), 63 deletions(-) diff --git a/content/en/content-management/page-resources.md b/content/en/content-management/page-resources.md index 6f746488c..4f902a67f 100644 --- a/content/en/content-management/page-resources.md +++ b/content/en/content-management/page-resources.md @@ -1,6 +1,6 @@ --- title: Page resources -description: Page resources -- images, other pages, documents, etc. -- have page-relative URLs and their own metadata. +description: Use page resources to logically associate assets with a page. categories: [content management] keywords: [bundle,content,resources] menu: @@ -37,82 +37,83 @@ content └── index.md (root of page bundle) ``` -## Properties +## Examples -ResourceType -: The main type of the resource's [Media Type](/templates/output-formats/#media-types). For example, a file of MIME type `image/jpeg` has the ResourceType `image`. A `Page` will have `ResourceType` with value `page`. +Use any of these methods on a `Page` object to capture page resources: -Name -: Default value is the file name (relative to the owning page). Can be set in front matter. + - [`Resources.ByType`] + - [`Resources.Get`] + - [`Resources.GetMatch`] + - [`Resources.Match`] -Title -: Default value is the same as `.Name`. Can be set in front matter. + Once you have captured a resource, use any of the applicable [`Resource`] methods to return a value or perform an action. -Permalink -: The absolute URL to the resource. Resources of type `page` will have no value. +[`Resource`]: /methods/resource +[`Resources.ByType`]: /methods/page/resources#bytype +[`Resources.GetMatch`]: /methods/page/resources#getmatch +[`Resources.Get`]: /methods/page/resources#get +[`Resources.Match`]: /methods/page/resources#match -RelPermalink -: The relative URL to the resource. Resources of type `page` will have no value. +The following examples assume this content structure: -Content -: The content of the resource itself. For most resources, this returns a string -with the contents of the file. Use this to create inline resources. +```text +content/ +└── example/ + ├── data/ + │ └── books.json <-- page resource + ├── images/ + │ ├── a.jpg <-- page resource + │ └── b.jpg <-- page resource + ├── snippets/ + │ └── text.md <-- page resource + └── index.md +``` + +Render a single image, and throw an error if the file does not exist: ```go-html-template -{{ with .Resources.GetMatch "script.js" }} - -{{ end }} - -{{ with .Resources.GetMatch "style.css" }} - -{{ end }} - -{{ with .Resources.GetMatch "img.png" }} - +{{ $path := "images/a.jpg" }} +{{ with .Resources.Get $path }} + +{{ else }} + {{ errorf "Unable to get page resource %q" $path }} {{ end }} ``` -MediaType.Type -: The media type (formerly known as a MIME type) of the resource (e.g., `image/jpeg`). - -MediaType.MainType -: The main type of the resource's media type (e.g., `image`). - -MediaType.SubType -: The subtype of the resource's type (e.g., `jpeg`). This may or may not correspond to the file suffix. - -MediaType.Suffixes -: A slice of possible file suffixes for the resource's media type (e.g., `[jpg jpeg jpe jif jfif]`). - -## Methods - -ByType -: Returns the page resources of the given type. +Render all images, resized to 300 px wide: ```go-html-template -{{ .Resources.ByType "image" }} +{{ range .Resources.ByType "image" }} + {{ with .Resize "300x" }} + + {{ end }} +{{ end }} ``` -Match -: Returns all the page resources (as a slice) whose `Name` matches the given Glob pattern ([examples](https://github.com/gobwas/glob/blob/master/readme.md)). The matching is case-insensitive. + +Render the markdown snippet: ```go-html-template -{{ .Resources.Match "images/*" }} +{{ with .Resources.Get "snippets/text.md" }} + {{ .Content }} +{{ end }} ``` -GetMatch -: Same as `Match` but will return the first match. +List the titles in the data file, and throw an error if the file does not exist. -### Pattern matching - -```go -// Using Match/GetMatch to find this images/sunset.jpg ? -.Resources.Match "images/sun*" ✅ -.Resources.Match "**/sunset.jpg" ✅ -.Resources.Match "images/*.jpg" ✅ -.Resources.Match "**.jpg" ✅ -.Resources.Match "*" 🚫 -.Resources.Match "sunset.jpg" 🚫 -.Resources.Match "*sunset.jpg" 🚫 +```go-html-template +{{ $path := "data/books.json" }} +{{ with .Resources.Get $path }} + {{ with . | transform.Unmarshal }} +

Books:

+
    + {{ range . }} +
  • {{ .title }}
    • + {{ end }} +
+ {{ end }} +{{ else }} + {{ errorf "Unable to get page resource %q" $path }} +{{ end }} ``` ## Metadata @@ -124,21 +125,21 @@ Resources of type `page` get `Title` etc. from their own front matter. {{% /note %}} name -: Sets the value returned in `Name`. +: (`string`) Sets the value returned in `Name`. {{% note %}} The methods `Match`, `Get` and `GetMatch` use `Name` to match the resources. {{% /note %}} title -: Sets the value returned in `Title` +: (`string`) Sets the value returned in `Title` params -: A map of custom key-value pairs. +: (`map`) A map of custom key-value pairs. ### Resources metadata example -{{< code-toggle >}} +{{< code-toggle file=content/example.md fm=true >}} title: Application date : 2018-01-25 resources : @@ -173,7 +174,7 @@ From the example above: - Every docx in the bundle will receive the `word` icon. {{% note %}} -The __order matters__ --- Only the **first set** values of the `title`, `name` and `params`-**keys** will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. +The order matters; only the first set values of the `title`, `name` and `params` keys will be used. Consecutive parameters will be set only for the ones not already set. In the above example, `.Params.icon` is first set to `"photo"` in `src = "documents/photo_specs.pdf"`. So that would not get overridden to `"pdf"` by the later set `src = "**.pdf"` rule. {{% /note %}} ### The `:counter` placeholder in `name` and `title` From 30c672d0b54b4c9a721dc922f38e838ce263d50d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Bj=C3=B8rn=20Erik=20Pedersen?= Date: Mon, 26 Aug 2024 16:33:58 +0200 Subject: [PATCH 33/36] netlify: Hugo 0.133.1 --- netlify.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/netlify.toml b/netlify.toml index 19c4e8a00..44c10a3c9 100644 --- a/netlify.toml +++ b/netlify.toml @@ -3,7 +3,7 @@ command = "hugo --gc --minify" [build.environment] - HUGO_VERSION = "0.133.0" + HUGO_VERSION = "0.133.1" [context.production.environment] HUGO_ENV = "production" From 45b732efa95d53c9f2e3031f35557fb42ef19c13 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Wed, 28 Aug 2024 06:58:21 -0700 Subject: [PATCH 34/36] Fix template lookup order for AMP pages --- data/docs.yaml | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/data/docs.yaml b/data/docs.yaml index 7ac76ee39..8d97c21e0 100644 --- a/data/docs.yaml +++ b/data/docs.yaml @@ -1865,7 +1865,7 @@ output: - layouts/_default/demolayout-baseof.html - layouts/_default/single-baseof.html - layouts/_default/baseof.html - - Example: AMP single page + - Example: AMP single page in "posts" section Kind: page OutputFormat: amp Suffix: html @@ -1874,17 +1874,17 @@ output: - layouts/posts/single.html - layouts/_default/single.amp.html - layouts/_default/single.html - - Example: AMP single page, French language + - Example: AMP single page in "posts" section, French language Kind: page - OutputFormat: html + OutputFormat: amp Suffix: html Template Lookup Order: - - layouts/posts/single.fr.html.html - - layouts/posts/single.html.html + - layouts/posts/single.fr.amp.html + - layouts/posts/single.amp.html - layouts/posts/single.fr.html - layouts/posts/single.html - - layouts/_default/single.fr.html.html - - layouts/_default/single.html.html + - layouts/_default/single.fr.amp.html + - layouts/_default/single.amp.html - layouts/_default/single.fr.html - layouts/_default/single.html - Example: Home page From a5c6bb4da85ded4d3d0d63d20d6855f2d6e0e91b Mon Sep 17 00:00:00 2001 From: Medcl Date: Thu, 29 Aug 2024 22:02:29 +0800 Subject: [PATCH 35/36] Add INFINI Pizza search engine --- content/en/tools/search.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/content/en/tools/search.md b/content/en/tools/search.md index 921d52f82..614bc511c 100644 --- a/content/en/tools/search.md +++ b/content/en/tools/search.md @@ -43,6 +43,10 @@ A static website with a dynamic search function? Yes, Hugo provides an alternati [Hugo Lyra](https://github.com/paolomainardi/hugo-lyra) : Hugo-Lyra is a JavaScript module to integrate [Lyra](https://github.com/LyraSearch/lyra) into a Hugo website. It contains the server-side part to generate the index and the client-side library (optional) to bootstrap the search engine easily. +[INFINI Pizza for WebAssembly](https://github.com/infinilabs/pizza-docsearch) +: Pizza is a super-lightweight yet fully featured search engine written in Rust. You can quickly add offline search functionality to your Hugo website in just five minutes with only three lines of code. For a step-by-step guide on integrating it with Hugo, check out [this blog tutorial](https://dev.to/medcl/adding-search-functionality-to-a-hugo-static-site-based-on-infini-pizza-for-webassembly-4h5e). + + ## Commercial [Algolia](https://www.algolia.com/) From a49697e536ee0d477ab4e552cfa8dc74debeff27 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sat, 31 Aug 2024 10:21:42 -0700 Subject: [PATCH 36/36] Add private use subtag requirements to multilingual page --- content/en/content-management/multilingual.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md index 4529eb1c4..b8ba80dfd 100644 --- a/content/en/content-management/multilingual.md +++ b/content/en/content-management/multilingual.md @@ -21,15 +21,22 @@ This is the default language configuration: In the above, `en` is the language key. -{{% note %}} -Each language key must conform to the syntax described in [RFC 5646]. You must use hyphens to separate subtags. For example: + +Language keys must conform to the syntax described in [RFC 5646]. For example: - `en` -- `en-GB` -- `pt-BR` +- `en-US` + +Artificial languages with private use subtags as defined in [RFC 5646 § 2.2.7] are also supported. Omit the `art-x-` prefix from the language key. For example: + +- `hugolang` + +{{% note %}} +Private use subtags must not exceed 8 alphanumeric characters. +{{% /note %}} [RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1 -{{% /note %}} +[RFC 5646 § 2.2.7]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.2.7 This is an example of a site configuration for a multilingual project. Any key not defined in a `languages` object will fall back to the global value in the root of your site configuration.