Squashed 'docs/' changes from fcc3ed651..a49697e53

a49697e53 Add private use subtag requirements to multilingual page a5c6bb4da Add INFINI Pizza search engine 45b732efa Fix template lookup order for AMP pages 30c672d0b netlify: Hugo 0.133.1 7c766e724 Update page resources documentation ca802fbec Document how to enable AsciiDoc syntax highlighting c3350f4cf Update definition of falsy to include zero time.Time values b0e5ab051 Fir typo 60f6cb63b Update migrations.md ec52c7ba1 Improve formatting of example code e5681ad01 Improve formatting of example code bdf3ffc73 Clarify the various next/prev methods b5505d22a Clarify template lookup order for shortcodes cf8dd7034 Improve embedded.md e5dee2651 Update transform.ToMath 4d419a128 Update pagination configuration to use new struct 05d4fd597 Update PrevInSection.md fd33370ed Add new-in 0.133.0 f9062042f Add the new page config section 205645e97 Remove out-dated new-in 3ed3673f7 Fix typo 41df91659 Document the 'else with' construct introduced with Go 1.23 9c4697ab3 netlify: Hugo 0.133.0 62506b052 Merge branch 'temp133' 877e1bfcd Add config options page.nextPrevSortOrder/nextPrevInSectionSortOrder eb159fe62 Update menu.md efa7795a0 Update theme dbe8911ad netlify: Hugo 0.132.2 2f793d328 Document passthrough render hooks a7ce9a5e8 netlify: Hugo 0.132.1 2c137cb48 Update blockquotes.md e0fa2f0d1 Add new-in badge to blockquote render hook page bf42bbe6b Update references to render hooks 85a3d9958 Update theme 2dae72128 Document blockquote render hooks 8f5afb55d Update plainify return type 160f22d0e netlify: Hugo 0.132.0 82b5586fb Document transform.ToMath 1efcbcddb tpl/transform: Make Plainify and ToMath return template.HTML 31727be2e docs: Regen docshelper 88a421426 Merge commit 'a6e635ca7d905d9ec3ffd708db2694f680b03aae' git-subtree-dir: docs git-subtree-split: a49697e536ee0d477ab4e552cfa8dc74debeff27
bep · Sep 1, 2024 · dec8cd4 · dec8cd4
1 parent a6e635c
commit dec8cd4
Show file tree

Hide file tree

Showing 46 changed files with 1,311 additions and 449 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
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/list.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/_default/list.html
diff --git a/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html b/_vendor/github.com/gohugoio/gohugoioTheme/layouts/shortcodes/gomodules-info.html
diff --git 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-20240815082608-66ccd383a90f
diff --git a/content/en/about/features.md b/content/en/about/features.md
@@ -49,7 +49,7 @@ toc: true
 : Leverage the embedded Markdown extensions to create tables, definition lists, footnotes, task lists, inserted text, mark text, subscripts, superscripts, and more.
 
 [Markdown render hooks]
-: Override the conversion of Markdown to HTML when rendering 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/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.|&nbsp;
 `content.value`|The content value as a string.|&nbsp;
@@ -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:

diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md
@@ -21,16 +21,23 @@ 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`
 
-[RFC 5646]: https://datatracker.ietf.org/doc/html/rfc5646#section-2.1
+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
+[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.
 
 {{< code-toggle file=hugo >}}

diff --git 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.
-
-```go-html-template
-{{ with .Resources.GetMatch "script.js" }}
-  <script>{{ .Content | safeJS }}</script>
-{{ end }}
+```text
+content/
+└── example/
+    ├── data/
+    │  └── books.json   <-- page resource
+    ├── images/
+    │  ├── a.jpg        <-- page resource
+    │  └── b.jpg        <-- page resource
+    ├── snippets/
+    │  └── text.md      <-- page resource
+    └── index.md
+```
 
-{{ with .Resources.GetMatch "style.css" }}
-  <style>{{ .Content | safeCSS }}</style>
-{{ end }}
+Render a single image, and throw an error if the file does not exist:
 
-{{ with .Resources.GetMatch "img.png" }}
-  <img src="data:{{ .MediaType.Type }};base64,{{ .Content | base64Encode }}">
+```go-html-template
+{{ $path := "images/a.jpg" }}
+{{ with .Resources.Get $path }}
+  <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+{{ 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" }}
+    <img src="{{ .RelPermalink }}" width="{{ .Width }}" height="{{ .Height }}" alt="">
+  {{ 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.
-
-### Pattern matching
+List the titles in the data file, and throw an error if the file does not exist.
 
-```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 }}
+    <p>Books:</p>
+    <ul>
+      {{ range . }}
+        <li>{{ .title }}</li>
+      {{ end }}
+    </ul>
+  {{ 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`

diff --git 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/_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.
diff --git 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
@@ -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/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]
 ---