all: Updates required for v0.123.0

Closes gohugoio#2385

content/en/content-management/multilingual.md

@@ -309,7 +309,7 @@ To create a list of links to translated content, use a template similar to the f
 <ul>
   {{ range .Translations }}
   <li>
-    <a href="{{ .RelPermalink }}">{{ .Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
+    <a href="{{ .RelPermalink }}">{{ .Language.Lang }}: {{ .LinkTitle }}{{ if .IsPage }} ({{ i18n "wordCount" . }}){{ end }}</a>
   </li>
   {{ end }}
 </ul>

content/en/content-management/page-bundles.md

@@ -18,16 +18,16 @@ A Page Bundle can be one of:
 - Leaf Bundle (leaf means it has no children)
 - Branch Bundle (home page, section, taxonomy terms, taxonomy list)
 
-|                                     | Leaf Bundle                                              | Branch Bundle                                                                                                                                                                                                      |
-|-------------------------------------|----------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Usage                               | Collection of content and attachments for single pages   | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list)                                                                                                                    |
-| Index file name                      | `index.md` [^fn:1]                                       | `_index.md` [^fn:1]                                                                                                                                                                                                |
-| Allowed Resources                   | Page and non-page (like images, PDF, etc.) types         | Only non-page (like images, PDF, etc.) types                                                                                                                                                                       |
-| Where can the Resources live?       | At any directory level within the leaf bundle directory. | Only in the directory level **of** the branch bundle directory i.e. the directory containing the `_index.md` ([ref](https://discourse.gohugo.io/t/question-about-content-folder-structure/11822/4?u=kaushalmodi)). |
-| Layout type                         | [`single`](/templates/single-page-templates/)            | [`list`](/templates/lists)                                                                                                                                                                                         |
-| Nesting                             | Does not allow nesting of more bundles under it          | Allows nesting of leaf or branch bundles under it                                                                                                                                                                  |
-| Example                             | `content/posts/my-post/index.md`                         | `content/posts/_index.md`                                                                                                                                                                                          |
-| Content from non-index page files...| Accessed only as page resources                          | Accessed only as regular pages                                                                                                                                                                                     |
+|                                     | Leaf Bundle                                              | Branch Bundle                                                                                   |
+|-------------------------------------|----------------------------------------------------------|-------------------------------------------------------------------------------------------------|
+| Usage                               | Collection of content and attachments for single pages   | Collection of attachments for section pages (home page, section, taxonomy terms, taxonomy list) |
+| Index file name                     | `index.md` [^fn:1]                                       | `_index.md` [^fn:1]                                                                             |
+| Allowed Resources                   | Page and non-page (like images, PDF, etc.) types         | Only non-page (like images, PDF, etc.) types                                                    |
+| Where can the Resources live?       | At any directory level within the leaf bundle directory. | At any directory level within the branch bundle directory.                                      |
+| Layout type                         | [`single`](/templates/single-page-templates/)            | [`list`](/templates/lists)                                                                      |
+| Nesting                             | Does not allow nesting of more bundles under it          | Allows nesting of leaf or branch bundles under it                                               |
+| Example                             | `content/posts/my-post/index.md`                         | `content/posts/_index.md`                                                                       |
+| Content from non-index page files...| Accessed only as page resources                          | Accessed only as regular pages                                                                  |
 
 ## Leaf bundles
 

content/en/content-management/shortcodes.md

@@ -206,46 +206,23 @@ Rendered:
 
 ### `instagram`
 
-The `instagram` shortcode uses Facebook's **oEmbed Read** feature. The  Facebook [developer documentation] states:
-
-- This permission or feature requires successful completion of the App Review process before your app can access live data. [Learn More]
-- This permission or feature is only available with business verification. You may also need to sign additional contracts before your app can access data. [Learn More Here]
-
-[developer documentation]: https://developers.facebook.com/docs/features-reference/oembed-read
-[Learn More]: https://developers.facebook.com/docs/app-review
-[Learn More Here]: https://developers.facebook.com/docs/development/release/business-verification
-
-You must obtain an Access Token to use the `instagram` shortcode.
-
-If your site configuration is private:
-
-{{< code-toggle file=hugo >}}
-[services.instagram]
-accessToken = 'xxx'
-{{< /code-toggle >}}
-
-If your site configuration is _not_ private, set the Access Token with an environment variable:
-
-```sh
-HUGO_SERVICES_INSTAGRAM_ACCESSTOKEN=xxx hugo --gc --minify
-```
-
-{{% note %}}
-If you are using a Client Access Token, you must combine the Access Token with your App ID using a pipe symbol (`APPID|ACCESSTOKEN`).
-{{% /note %}}
 
 To display an Instagram post with this URL:
 
 ```text
-https://www.instagram.com/p/BWNjjyYFxVx/
+https://www.instagram.com/p/CxOWiQNP2MO/
 ```
 
 Include this in your markdown:
 
 ```text
-{{</* instagram BWNjjyYFxVx */>}}
+{{</* instagram CxOWiQNP2MO */>}}
 ```
 
+Rendered:
+
+{{< instagram CxOWiQNP2MO >}}
+
 ### `param`
 
 Gets a value from the current `Page's` parameters set in front matter, with a fallback to the site parameter value. It will log an `ERROR` if the parameter with the given key could not be found in either.

content/en/functions/data/GetCSV.md

@@ -15,6 +15,18 @@ action:
 toc: true
 ---
 
+{{% deprecated-in 0.123.0 %}}
+Instead, use [`transform.Unmarshal`] with a [global], [page], or [remote] resource.
+
+See the [remote data example].
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[global]: /getting-started/glossary/#global-resource
+[page]: /getting-started/glossary/#page-resource
+[remote data example]: /functions/resources/getremote/#remote-data
+[remote]: /getting-started/glossary/#remote-resource
+{{% /deprecated-in %}}
+
 Given the following directory structure:
 
 ```text

content/en/functions/data/GetJSON.md

@@ -15,6 +15,18 @@ action:
 toc: true
 ---
 
+{{% deprecated-in 0.123.0 %}}
+Instead, use [`transform.Unmarshal`] with a [global], [page], or [remote] resource.
+
+See the [remote data example].
+
+[`transform.Unmarshal`]: /functions/transform/unmarshal/
+[global]: /getting-started/glossary/#global-resource
+[page]: /getting-started/glossary/#page-resource
+[remote data example]: /functions/resources/getremote/#remote-data
+[remote]: /getting-started/glossary/#remote-resource
+{{% /deprecated-in %}}
+
 Given the following directory structure:
 
 ```text

content/en/functions/fmt/Errorf.md

@@ -8,6 +8,7 @@ action:
   related:
     - functions/fmt/Erroridf
     - functions/fmt/Warnf
+    - functions/fmt/Warnidf
   returnType: string
   signatures: ['fmt.Errorf FORMAT [INPUT]']
 aliases: [/functions/errorf]

content/en/functions/fmt/Erroridf.md

@@ -8,14 +8,15 @@ action:
   related:
     - functions/fmt/Errorf
     - functions/fmt/Warnf
+    - functions/fmt/Warnidf
   returnType: string
   signatures: ['fmt.Erroridf ID FORMAT [INPUT]']
 aliases: [/functions/erroridf]
 ---
 
 {{% include "functions/fmt/_common/fmt-layout.md" %}}
 
-The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreErrors` array in your site configuration.
+The `erroridf` function evaluates the format string, then prints the result to the ERROR log and fails the build. Unlike the [`errorf`] function, you may suppress errors logged by the `erroridf` function by adding the message ID to the `ignoreLogs` array in your site configuration.
 
 This template code:
 
@@ -28,13 +29,13 @@ Produces this console log:
 ```text
 ERROR You should consider fixing this.
 You can suppress this error by adding the following to your site configuration:
-ignoreErrors = ['error-42']
+ignoreLogs = ['error-42']
 ```
 
 To suppress this message:
 
 {{< code-toggle file=hugo >}}
-ignoreErrors = ["error-42"]
+ignoreLogs = ["error-42"]
 {{< /code-toggle >}}
 
 [`errorf`]: /functions/fmt/errorf

content/en/functions/fmt/Warnf.md

@@ -8,6 +8,7 @@ action:
   related:
     - functions/fmt/Errorf
     - functions/fmt/Erroridf
+    - functions/fmt/Warnidf
   returnType: string
   signatures: ['fmt.Warnf FORMAT [INPUT]']
 aliases: [/functions/warnf]

content/en/functions/fmt/Warnidf.md

@@ -0,0 +1,43 @@
+---
+title: fmt.Warnidf
+description: Log a suppressable WARNING from a template.
+categories: []
+keywords: []
+action:
+  aliases: [warnidf]
+  related:
+    - functions/fmt/Errorf
+    - functions/fmt/Erroridf
+    - functions/fmt/Warnf
+  returnType: string
+  signatures: ['fmt.Warnidf ID FORMAT [INPUT]']
+aliases: [/functions/warnidf]
+---
+
+{{< new-in 0.123.0 >}}
+
+{{% include "functions/fmt/_common/fmt-layout.md" %}}
+
+The `warnidf` function evaluates the format string, then prints the result to the WARNING log. Unlike the [`warnf`] function, you may suppress warnings logged by the `warnidf` function by adding the message ID to the `ignoreLogs` array in your site configuration.
+
+This template code:
+
+```go-html-template
+{{ warnidf "warning-42" "You should consider fixing this." }}
+```
+
+Produces this console log:
+
+```text
+WARN You should consider fixing this.
+You can suppress this warning by adding the following to your site configuration:
+ignoreLogs = ['warning-42']
+```
+
+To suppress this message:
+
+{{< code-toggle file=hugo >}}
+ignoreLogs = ["warning-42"]
+{{< /code-toggle >}}
+
+[`warnf`]: /functions/fmt/warnf

content/en/getting-started/configuration-markup.md

@@ -56,9 +56,32 @@ This is the default configuration for the Goldmark markdown renderer:
 
 {{< code-toggle config=markup.goldmark />}}
 
-For details on the extensions, refer to the [Goldmark documentation](https://github.com/yuin/goldmark/#built-in-extensions).
+### Goldmark extensions
 
-Some settings explained:
+
+Extension|Documentation
+:--|:--
+cjk|[Goldmark Extensions: CJK]
+definitionList|[PHP Markdown Extra: Definition lists]
+footnote|[PHP Markdown Extra: Footnotes]
+linkify|[GitHub Flavored Markdown: Autolinks]
+passthrough|[Hugo Goldmark Extensions: Passthrough]
+strikethrough|[GitHub Flavored Markdown: Strikethrough]
+table|[GitHub Flavored Markdown: Tables]
+taskList|[GitHub Flavored Markdown: Task list items]
+typographer|[Goldmark Extensions: Typographer]
+
+[GitHub Flavored Markdown: Autolinks]: https://github.github.com/gfm/#autolinks-extension-
+[GitHub Flavored Markdown: Strikethrough]: https://github.github.com/gfm/#strikethrough-extension-
+[GitHub Flavored Markdown: Tables]: https://github.github.com/gfm/#tables-extension-
+[GitHub Flavored Markdown: Task list items]: https://github.github.com/gfm/#task-list-items-extension-
+[Goldmark Extensions: CJK]: https://github.com/yuin/goldmark?tab=readme-ov-file#cjk-extension
+[Goldmark Extensions: Typographer]: https://github.com/yuin/goldmark?tab=readme-ov-file#typographer-extension
+[Hugo Goldmark Extensions: Passthrough]: https://github.com/gohugoio/hugo-goldmark-extensions?tab=readme-ov-file#passthrough-extension
+[PHP Markdown Extra: Definition lists]: https://michelf.ca/projects/php-markdown/extra/#def-list
+[PHP Markdown Extra: Footnotes]: https://michelf.ca/projects/php-markdown/extra/#footnotes
+
+### Goldmark settings
 
 hardWraps
 : By default, Goldmark ignores newlines within a paragraph. Set to `true` to render newlines as `<br>` elements.

content/en/methods/page/BundleType.md

@@ -5,7 +5,7 @@ categories: []
 keywords: []
 action:
   related: []
-  returnType: files.ContentClass
+  returnType: string
   signatures: [PAGE.BundleType]
 ---
 

content/en/methods/page/File.md

@@ -80,33 +80,33 @@ The path separators (slash or backslash) in `Path`, `Dir`, and `Filename` depend
 {{ end }}
 ```
 
-###### Lang
+###### LogicalName
 
-(`string`) The language associated with the given file.
+(`string`) The file name.
 
 ```go-html-template
 {{ with .File }}
-  {{ .Lang }}
+  {{ .LogicalName }}
 {{ end }}
 ```
 
-###### LogicalName
+###### Path
 
-(`string`) The file name.
+(`string`) The file path, relative to the `content` directory.
 
 ```go-html-template
 {{ with .File }}
-  {{ .LogicalName }}
+  {{ .Path }}
 {{ end }}
 ```
 
-###### Path
+###### Section
 
-(`string`) The file path, relative to the `content` directory.
+(`string`) The name of the top level section in which the file resides.
 
 ```go-html-template
 {{ with .File }}
-  {{ .Path }}
+  {{ .Section }}
 {{ end }}
 ```
 
@@ -157,9 +157,9 @@ ContentBaseName|a|b|news
 Dir|news/|news/b/|news/
 Ext|md|md|md
 Filename|/home/user/...|/home/user/...|/home/user/...
-Lang|en|en|en
 LogicalName|a.en.md|index.en.md|_index.en.md
 Path|news/a.en.md|news/b/index.en.md|news/_index.en.md
+Section|news|news|news
 TranslationBaseName|a|index|_index
 UniqueID|15be14b...|186868f...|7d9159d...
 

content/en/methods/page/Path.md

@@ -0,0 +1,46 @@
+---
+title: Path
+description: Returns the canonical content path for the given page.
+categories: []
+keywords: []
+action:
+  related: []
+  returnType: string
+  signatures: [PAGE.Path]
+---
+
+The `Path` method on a `Page` object returns the canonical content path for the given page, regardless of whether the page is backed by a file. 
+
+```go-html-template
+{{ .Path }} → /posts/post-1
+```
+
+This value is neither a file path nor a relative URL. It is canonical identifier for each page, independent of content format and URL.
+
+{{% note %}}
+Beginning with the release of [v0.92.0] in January 2022, Hugo emitted a warning whenever the `Path` method was called. The warning indicated that this method would change in a future release.
+
+The meaning of, and value returned by, the `Path` method on a `Page` object changed with the release of v0.123.0 in February 2024.
+
+[v0.92.0]: https://github.com/gohugoio/hugo/releases/tag/v0.92.0
+{{% /note %}}
+
+For example, if you were to change a page's URL by specifying either `slug` or `url` in front matter, the value returned by the `Path` method will not change:
+
+File path|Front matter slug|Value returned by .Path
+:--|:--|:--
+`content/_index.md`||`/`
+`content/posts/_index.md`||`/posts`
+`content/posts/post-1.md`|`foo`|`/posts/post-1`
+`content/posts/post-2.html`|`bar`|`/posts/post-2`
+
+With multilingual sites, for languages other than the default content language, Hugo appends a language identifier. For example, for a site where the default content language is English:
+
+File path|Value returned by .Path
+:--|:--
+`content/_index.en.md`|`/`
+`content/_index.de.md`|`/_index.de`
+`content/posts/_index.en.md`|`/posts`
+`content/posts/_index.de.md`|`/posts/_index.de`
+`content/posts/posts-1.en.md`|`/posts/post-1`
+`content/posts/posts-1.de.md`|`/posts/post-1.de`

content/en/methods/site/LastChange.md

@@ -9,10 +9,16 @@ action:
   signatures: [SITE.LastChange]
 ---
 
+{{% deprecated-in 0.123.0 %}}
+Use [`.Site.Lastmod`] instead.
+
+[`.Site.Lastmod`]: /methods/site/lastmod/
+{{% /deprecated-in %}}
+
 The `LastChange` method on a `Site` object returns a [`time.Time`] value. Use this with time [functions] and [methods]. For example:
 
 ```go-html-template
-{{ .Site.LastChange | time.Format ":date_long" }} → October 16, 2023
+{{ .Site.LastChange | time.Format ":date_long" }} → January 31, 2024
 
 ```