Document additional changes in v0.125.0

content/en/functions/strings/Diff/index.md

@@ -0,0 +1,33 @@
+---
+title: strings.Diff
+description: Returns an anchored diff of the two texts old and new in the unified diff format. If old and new are identical, returns an empty string.
+categories: []
+keywords: []
+action:
+  related: []
+  returnType: string
+  signatures: [strings.Diff OLDNAME OLD NEWNAME NEW]
+---
+
+{{< new-in 0.125.0 >}}
+
+Use `strings.Diff` to compare two strings and render a highlighted diff:
+
+```go-html-template
+{{ $want = `
+<p>The product of 6 and 7 is 42.</p>
+<p>The product of 7 and 6 is 42.</p>
+`}}
+
+{{ $got = `
+<p>The product of 6 and 7 is 42.</p>
+<p>The product of 7 and 6 is 13.</p>
+`}}
+
+{{ $diff := strings.Diff "want" $want "got" $got" }}
+{{ transform.Highlight $diff "diff" }}
+```
+
+Rendered:
+
+![sreen capture](diff-screen-capture.png)

content/en/methods/page/RenderShortcodes.md

@@ -22,11 +22,12 @@ Use this method in shortcode templates to compose a page from multiple content f
 For example:
 
 {{< code file=layouts/shortcodes/include.html >}}
-{{ $p := site.GetPage (.Get 0) }}
-{{ $p.RenderShortcodes }}
+{{ with site.GetPage (.Get 0) }}
+  {{ .RenderShortcodes }}
+{{ end }}
 {{< /code >}}
 
-Then in your Markdown:
+Then call the shortcode in your Markdown:
 
 {{< code file=content/about.md lang=md >}}
 {{%/* include "/snippets/services.md" */%}}

content/en/methods/page/Sitemap.md

@@ -14,15 +14,22 @@ Access to the `Sitemap` method on a `Page` object is restricted to [sitemap temp
 
 ## Methods
 
-ChangeFreq
-: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is "" (change frequency omitted from rendered sitemap).
+changefreq
+: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef).
 
 ```go-html-template
 {{ .Sitemap.ChangeFreq }}
 ```
 
-Priority
-: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is -1 (priority omitted from rendered sitemap).
+disable {{< new-in 0.125.0 >}}
+: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
+
+```go-html-template
+{{ .Sitemap.Disable }}
+```
+
+priority
+: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0.  With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#priority).
 
 ```go-html-template
 {{ .Sitemap.Priority }}

content/en/render-hooks/_common/_index.md

@@ -0,0 +1,13 @@
+---
+cascade:
+  _build:
+    list: never
+    publishResources: false
+    render: never
+---
+
+<!--
+Files within this headless branch bundle are Markdown snippets. Each file must contain front matter delimiters, though front matter fields are not required.
+
+Include the rendered content using the "include" shortcode. 
+-->

content/en/render-hooks/_common/pageinner.md

@@ -0,0 +1,42 @@
+---
+# Do not remove front matter.
+---
+
+## PageInner
+
+{{< new-in 0.125.0 >}}
+
+The primary use case for `PageInner` is to resolve links and [page resources] relative to an included `Page`. For example, create an "include" shortcode to compose a page from multiple content files, while preserving a global context for footnotes and the table of contents:
+
+{{< code file=layouts/shortcodes/include.html >}}
+{{ with site.GetPage (.Get 0) }}
+  {{ .RenderShortcodes }}
+{{ end }}
+{{< /code >}}
+
+Then call the shortcode in your Markdown:
+
+{{< code file=content/posts/p1.md >}}
+{{%/* include "/posts/p2" */%}}
+{{< /code >}}
+
+Any render hook triggered while rendering `/posts/p2` will get:
+
+- `/posts/p1` when calling `Page`
+- `/posts/p2` when calling `PageInner`
+
+`PageInner` falls back to the value of `Page` if not relevant, and always returns a value.
+
+{{% note %}}
+The `PageInner` method is only relevant for shortcodes that invoke the [`RenderShortcodes`] method, and you must call the shortcode using the `{{%/*..*/%}}` notation.
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+{{% /note %}}
+
+As a practical example, Hugo's embedded link and image render hooks use the `PageInner` method to resolve markdown link and image destinations. See the source code for each:
+
+- [Embedded link render hook]({{% eturl render-link %}})
+- [Embedded image render hook]({{% eturl render-image %}})
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes/
+[page resources]: /getting-started/glossary/#page-resource

content/en/render-hooks/code-blocks.md

@@ -76,7 +76,15 @@ Code block render hook templates receive the following [context]:
 
 ###### Page
 
-(`page`) A reference to the page containing the code block.
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
 
 ###### Position
 
@@ -140,3 +148,5 @@ Hugo includes an [embedded code block render hook] to render [GoAT diagrams].
 
 [embedded code block render hook]: {{% eturl render-codeblock-goat %}}
 [GoAT diagrams]: /content-management/diagrams/#goat-diagrams-ascii
+
+{{% include "/render-hooks/_common/pageinner.md" %}}

content/en/render-hooks/headings.md

@@ -37,7 +37,15 @@ title = true
 
 ###### Page
 
-(`page`) A reference to the page containing the heading.
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
 
 ###### PlainText
 
@@ -67,3 +75,5 @@ To add an anchor link to the right of each heading:
   <a href="#{{ .Anchor }}">#</a>
 </h{{ .Level }}>
 {{< /code >}}
+
+{{% include "/render-hooks/_common/pageinner.md" %}}

content/en/render-hooks/images.md

@@ -55,7 +55,15 @@ block = true
 
 ###### Page
 
-(`page`) A reference to the page containing the image.
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
 
 ###### PlainText
 
@@ -151,3 +159,5 @@ target = 'assets'
 {{< /code-toggle >}}
 
 Note that the embedded image render hook does not perform image processing. Its sole purpose is to resolve Markdown image destinations.
+
+{{% include "/render-hooks/_common/pageinner.md" %}}

content/en/render-hooks/links.md

@@ -38,7 +38,15 @@ Link render hook templates receive the following context:
 
 ###### Page
 
-(`page`) A reference to the page containing the link.
+(`page`) A reference to the current page.
+
+###### PageInner
+
+{{< new-in 0.125.0 >}}
+
+(`page`) A reference to a page nested via the [`RenderShortcodes`] method. [See details](#pageinner).
+
+[`RenderShortcodes`]: /methods/page/rendershortcodes
 
 ###### PlainText
 
@@ -121,3 +129,5 @@ target = 'assets'
 source = 'static'
 target = 'assets'
 {{< /code-toggle >}}
+
+{{% include "/render-hooks/_common/pageinner.md" %}}

content/en/templates/sitemap-template.md

@@ -28,18 +28,21 @@ With a multilingual project, Hugo generates:
 
 ## Configuration
 
-Set the default values for [change frequency] and [priority], and the name of the generated file, in your site configuration.
+These are the default sitemap configuration values. They apply to all pages unless overridden in front matter.
 
 {{< code-toggle config=sitemap />}}
 
 changefreq
-: How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. Default is `""` (change frequency omitted from rendered sitemap).
+: (`string`) How frequently a page is likely to change. Valid values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly`, and `never`. With the default value of `""` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#changefreqdef).
+
+disable {{< new-in 0.125.0 >}}
+: (`bool`) Whether to disable page inclusion. Default is `false`. Set to `true` in front matter to exclude the page.
 
 filename
-: The name of the generated file. Default is `sitemap.xml`.
+: (`string`) The name of the generated file. Default is `sitemap.xml`.
 
 priority
-: The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0. Default is `-1` (priority omitted from rendered sitemap).
+: (`float`) The priority of a page relative to any other page on the site. Valid values range from 0.0 to 1.0.  With the default value of `-1` Hugo will omit this field from the sitemap. See [details](https://www.sitemaps.org/protocol.html#priority).
 
 ## Override default values
 
@@ -49,6 +52,7 @@ Override the default values for a given page in front matter.
 title = 'News'
 [sitemap]
   changefreq = 'weekly'
+  disable = true
   priority = 0.8
 {{</ code-toggle >}}
 
@@ -75,6 +79,4 @@ disableKinds = ['sitemap']
 {{</ code-toggle >}}
 
 [`publishDir`]: /getting-started/configuration#publishdir
-[change frequency]: <https://www.sitemaps.org/protocol.html#changefreqdef>
-[priority]: <https://www.sitemaps.org/protocol.html#priority>
 [sitemap protocol]: <https://www.sitemaps.org/protocol.html>

data/docs.yaml

@@ -1557,10 +1557,8 @@ config:
     disqus:
       disable: false
     googleAnalytics:
-      anonymizeIP: false
       disable: false
       respectDoNotTrack: false
-      useSessionStorage: false
     instagram:
       disable: false
       simple: false
@@ -1651,6 +1649,7 @@ config:
       disableInlineCSS: false
   sitemap:
     changeFreq: ""
+    disable: false
     filename: sitemap.xml
     priority: -1
   social: null
@@ -2799,8 +2798,8 @@ tpl:
             {{ $m.Set "Hugo" "Rocks!" }}
             {{ $m.Values | debug.Dump | safeHTML }}
           - |-
-            map[string]interface {}{
-              "Hugo": "Rocks!",
+            {
+              "Hugo": "Rocks!"
             }
       TestDeprecationErr:
         Aliases: null