Squashed 'docs/' changes from ccb1b97cb..159c843fd

159c843fd Fix front matter menu entry example
c3a476a19 Document soft deprecation of PAGE.Scratch
cdead9785 netlify: Hugo 0.138.0
9169b4da4 Update version references
3bc6bf431 Update embedded.md
5c7743b2e Update creation instructions for the emoji quick reference
109efe3eb Document the comment shortcode
83d7d3005 Update theme
d3c205054 netlify: Hugo 0.137.1
545290351 Handle inline HTML content
0204be97d Update theme
18d09235e Remove JS and CSS that prevents FOUC with client side math rendering
63d9dd876 Update RenderShortcodes.md
064b95539 Update output-format-definition.md
3744f3be2 Describe and refer to the extended/deploy edition
3d3302308 netlify: Hugo 0.137.0
b53aedcea Update RenderShortcodes.md
b5f289165 Replace HTML comments in markdown with the new comment shortcode
c673880b6 Remove superfluous right bracket
f80b0c61e Update faq.md
2ede707eb Document installation on NixOS
09b114914 Update theme
76a9f90b2 Update passthrough.md
9f3355630 Update Scratch.md
bc080ecaa Update Store.md
1507ede32 Update Scratch.md
54a90f569 Update Store.md
7c9145c43 Fix broken link
dd15f183b Update ToMath.md
2b021c34b Move the [build] documentation to its own page
cbb6677ec Fix typo
ac0969063 Update ToMath.md
7fbdfd7c8 netlify: Hugo 0.136.5
17f54223c Update ToMath.md
4c9c3bb06 Update multilingual.md
1432da7bd Make site and page language methods linkable
fd5b746cb Update urls.md
a746f1b3a Update urls.md
abf8738e2 netlify: Hugo 0.136.4
bd8759996 Update TrimSpace.md
6103c1e84 Documents strings.TrimSpace
533dd3a7b netlify: Hugo 0.136.3
30f3f97cf Update quick-start.md
b0d7b41a0 Update configuration-markup.md
760e5e4f0 Update quick-start.md
17daeb866 Update quick-start.md
1e158e723 netlify: Hugo 0.136.2
d32530839 Update theme
edb9bee02 Update description of url front matter field
e1c576e18 netlify: Hugo 0.136.1
1ad28e1e0 Describe how to configure uglyURLs per section
cbbd4c4fe netlify: Hugo 0.136.0
bb7f35e99 Merge branch 'tempv0.136.0'
706110736 docs: Regen CLI docs
bf0c7821f Update urls.md
8c544e6c0 Update quick-start.md
8d02733d0 Update Paginator.md
a45327aac Update Paginate.md
1377ed4de Clarify date parsing
e19fb8043 Document front matter date field aliases
a39951847 Update Tailwind CSS installation instructions
3be164c35 Remove duplicate token
05fc815f7 commands: Add "hugo build" as an alias for "hugo"
cb3cb504c Update table render hook example
efbee0bff Clarify resources.GetRemote 404 handling
4312d49c9 Update compare.Conditional documentation
4a46d53b6 Update theme
93e542d4f netlify: Hugo 0.135.0
b4da1c104 Remvoe some old new-in shortcodes
4c316f051 Update TailwindCSS.md
c2fe91509 Update introduction.md
906b7c66b Update configuration.md
5ab6b3cdd Update documentation.md
26fb4bb4c Update documentation.md
e9e917f37 Update version refs
83ce07f24 netlify: Hugo 0.134.3
8cb32f802 Update front-matter.md
94d7f576a Update faq.md
fafc1d8d9 netlify: Hugo 0.134.2
bfe9cdc3d Update content-adapters.md
9e49ae3e1 Document ignoreLogs configuration setting
6b47a1d57 Update configuration.md
fd98a0372 Document CLI options that can be set in configuration
07c2400d8 Document alternative to Summary method
d053fa163 Update to reflect changes in v0.134.1
137dc3241 Update ContentWithoutSummary.md
e8f6427d9 netlify: Hugo 0.134.1

git-subtree-dir: docs
git-subtree-split: 159c843fd79e94a0f49bee74c272cd0cc4a848a2

9 files changed, 154 insertions, 50 deletions

diff --git a/content/en/content-management/content-adapters.md b/content/en/content-management/content-adapters.md
index 4d5bd0890..a88bdba5f 100644
--- a/content/en/content-management/content-adapters.md
+++ b/content/en/content-management/content-adapters.md
@@ -91,6 +91,10 @@ Returns the `Site` to which the pages will be added.
 {{ .Site.Title }}
 {{< /code >}}
 
+{{% note %}}
+Note that the `Site` returned isn't fully built when invoked from the content adapters; if you try to call methods that depends on pages, e.g. `.Site.Pages`, you will get an error saying "this method cannot be called before the site is fully initialized".
+{{% /note %}}
+
 ###### Store
 
 Returns a persistent “scratch pad” to store and manipulate data. The main use case for this is to transfer values between executions when [EnableAllLanguages](#enablealllanguages) is set. See [examples](/methods/page/store/).
diff --git a/content/en/content-management/formats.md b/content/en/content-management/formats.md
index e96bc5af3..1132c888c 100644
--- a/content/en/content-management/formats.md
+++ b/content/en/content-management/formats.md
@@ -59,7 +59,7 @@ Create your content in [HTML] preceded by front matter. The content is typically
 
 ### Emacs Org Mode
 
-Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode)).
+Create your content in the [Emacs Org Mode] format preceded by front matter. You can use Org Mode keywords for front matter. See [details](/content-management/front-matter/#emacs-org-mode).
 
 ### AsciiDoc
 
diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md
index 3ac2a63bc..5cbf645a5 100644
--- a/content/en/content-management/front-matter.md
+++ b/content/en/content-management/front-matter.md
@@ -39,7 +39,7 @@ weight = 10
 author = 'John Smith'
 {{< /code-toggle >}}
 
-Front matter fields may be [scalar], [arrays], or [maps] containing [boolean], [integer], [float], or [string] values. Note that the TOML format also supports date/time values using unquoted strings.
+Front matter fields may be [boolean], [integer], [float], [string], [arrays], or [maps]. Note that the TOML format also supports unquoted date/time values.
 
 [scalar]: /getting-started/glossary/#scalar
 [arrays]: /getting-started/glossary/#array
@@ -80,7 +80,8 @@ The field names below are reserved. For example, you cannot create a custom fiel
 
 ###### date
 
-(`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Date`] method on a `Page` object.
+(`string`) The date associated with the page, typically the creation date. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Date`] method on a `Page` object.
+
 
 [`date`]: /methods/page/date/
 
@@ -99,7 +100,7 @@ If `true`, the page will not be rendered unless you pass the `--buildDrafts` fla
 
 ###### expiryDate
 
-(`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`ExpiryDate`] method on a `Page` object.
+(`string`) The page expiration date. On or after the expiration date, the page will not be rendered unless you pass the `--buildExpired` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`ExpiryDate`] method on a `Page` object.
 
 [`expirydate`]: /methods/page/expirydate/
 
@@ -127,6 +128,7 @@ If `true`, the page will not be rendered unless you pass the `--buildDrafts` fla
 [`keywords`]: /methods/page/keywords/
 [taxonomy]: /getting-started/glossary/#taxonomy
 
+{{% comment %}}
 <!-- Added in v0.123.0 but purposefully omitted from documentation. -->
 <!--
 kind
@@ -138,10 +140,11 @@ kind
 lang
 : The language code for this page. This is usually derived from the module mount or filename.
 -->
+{{% /comment %}}
 
 ###### lastmod
 
-(`string`) The date that the page was last modified. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`Lastmod`] method on a `Page` object.
+(`string`) The date that the page was last modified. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`Lastmod`] method on a `Page` object.
 
 [`lastmod`]: /methods/page/date/
 
@@ -167,21 +170,27 @@ lang
 
 ###### menus
 
-(`string`,`string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
+(`string`, `string array`, or `map`) If set, Hugo adds the page to the given menu or menus. See the [menus] page for details.
 
 [menus]: /content-management/menus/#define-in-front-matter
 
+###### modified
+
+Alias to [lastmod](#lastmod).
+
 ###### outputs
 
 (`string array`) The [output formats] to render.
 
 [output formats]: /templates/output-formats/
 
+{{% comment %}}
 <!-- Added in v0.123.0 but purposefully omitted from documentation. -->
 <!--
 path
 : The canonical page path.
 -->
+{{% /comment %}}
 
 ###### params
 
@@ -191,12 +200,20 @@ path
 
 [page parameters]: #parameters
 
+###### pubdate
+
+Alias to [publishDate](#publishdate).
+
 ###### publishDate
 
-(`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports date/time values using unquoted strings. Access this value from a template using the [`PublishDate`] method on a `Page` object.
+(`string`) The page publication date. Before the publication date, the page will not be rendered unless you pass the `--buildFuture` flag to the `hugo` command. Note that the TOML format also supports unquoted date/time values. See the [dates](#dates) section for examples. Access this value from a template using the [`PublishDate`] method on a `Page` object.
 
 [`publishdate`]: /methods/page/publishdate/
 
+###### published
+
+Alias to [publishDate](#publishdate).
+
 ###### resources
 
 (`map array`) An array of maps to provide metadata for [page resources].
@@ -242,6 +259,10 @@ path
 [content type]: /getting-started/glossary/#content-type
 [`type`]: /methods/page/type/
 
+###### unpublishdate
+
+Alias to [expirydate](#expirydate).
+
 ###### url
 
 (`string`) Overrides the entire URL path. Applicable to regular pages and section pages. See the [URL management] page for details.
@@ -428,3 +449,15 @@ Note that you can also specify array elements on a single line:
 
 [content format]: /content-management/formats/
 [emacs org mode]: https://orgmode.org/
+
+## Dates
+
+When populating a date field, whether a [custom page parameter](#parameters) or one of the four predefined fields ([`date`](#date), [`expiryDate`](#expirydate), [`lastmod`](#lastmod), [`publishDate`](#publishdate)), use one of these parsable formats:
+
+{{% include "functions/time/_common/parsable-date-time-strings.md" %}}
+
+To override the default time zone, set the [`timeZone`](https://gohugo.io/getting-started/configuration/#timezone) in your site configuration. The order of precedence for determining the time zone is:
+
+1. The time zone offset in the date/time string
+2. The time zone specified in your site configuration
+3. The `Etc/UTC` time zone
diff --git a/content/en/content-management/image-processing/index.md b/content/en/content-management/image-processing/index.md
index db786361c..841f12863 100644
--- a/content/en/content-management/image-processing/index.md
+++ b/content/en/content-management/image-processing/index.md
@@ -205,8 +205,6 @@ Sometimes it can be useful to create the filter chain once and then reuse it.
 
 ### Colors
 
-{{< new-in 0.104.0 >}}
-
 `.Colors` returns a slice of hex strings with the dominant colors in the image using a simple histogram method.
 
 ```go-html-template
diff --git a/content/en/content-management/menus.md b/content/en/content-management/menus.md
index 169b6eb05..ff2011d3d 100644
--- a/content/en/content-management/menus.md
+++ b/content/en/content-management/menus.md
@@ -100,7 +100,7 @@ This front matter menu entry demonstrates some of the available properties:
 
 {{< code-toggle file=content/products/software.md fm=true >}}
 title = 'Software'
-[[menus.main]]
+[menus.main]
 parent = 'Products'
 weight = 20
 pre = '<i class="fa-solid fa-code"></i>'
diff --git a/content/en/content-management/multilingual.md b/content/en/content-management/multilingual.md
index b8ba80dfd..165b2402e 100644
--- a/content/en/content-management/multilingual.md
+++ b/content/en/content-management/multilingual.md
@@ -136,7 +136,7 @@ In the example above, all settings except `color` below `params` map to predefin
 
 ```go-html-template
 {{ site.Title }}
-{{ site.LanguageCode }}
+{{ site.Language.LanguageCode }}
 {{ site.Params.color }}
 ```
 
diff --git a/content/en/content-management/shortcodes.md b/content/en/content-management/shortcodes.md
index 847ba2bbb..8e345f2fb 100644
--- a/content/en/content-management/shortcodes.md
+++ b/content/en/content-management/shortcodes.md
@@ -74,6 +74,26 @@ You can call shortcodes within other shortcodes by creating your own templates t
 
 Use these embedded shortcodes as needed.
 
+### comment
+
+{{< new-in "0.137.1" >}}
+
+{{% note %}}
+To override Hugo's embedded `comment` shortcode, copy the [source code] to a file with the same name in the layouts/shortcodes directory.
+
+[source code]: {{% eturl comment %}}
+{{% /note %}}
+
+Use the `comment` shortcode to include comments in your Markdown. Hugo excludes the encapsulated text when rendering your site.
+
+Example usage:
+
+```text
+{{%/* comment */%}} TODO: rewrite the paragraph below. {{%/* /comment */%}}
+```
+
+Although you can call this shortcode using the `{{</* */>}}` notation, computationally it is more efficient to call it using the `{{%/* */%}}` notation as shown above.
+
 ### figure
 
 {{% note %}}
diff --git a/content/en/content-management/summaries.md b/content/en/content-management/summaries.md
index e0b2c9590..07c61d963 100644
--- a/content/en/content-management/summaries.md
+++ b/content/en/content-management/summaries.md
@@ -12,35 +12,34 @@ weight: 160
 toc: true
 aliases: [/content/summaries/,/content-management/content-summaries/]
 ---
-
+{{% comment %}}
 <!-- Do not remove the manual summary divider below. -->
 <!-- If you do, you will break its first literal usage on this page. -->
+{{% /comment %}}
 <!--more-->
 
-You can define a content summary manually, in front matter, or automatically. A manual content summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
+You can define a summary manually, in front matter, or automatically. A manual summary takes precedence over a front matter summary, and a front matter summary takes precedence over an automatic summary.
 
 Review the [comparison table](#comparison) below to understand the characteristics of each summary type.
 
 ## Manual summary
 
-Use a `<!--more-->` divider to indicate the end of the content summary. Hugo will not render the summary divider itself.
+Use a `<!--more-->` divider to indicate the end of the summary. Hugo will not render the summary divider itself.
 
-{{< code file=content/sample.md >}}
+{{< code file=content/example.md >}}
 +++
 title: 'Example'
 date: 2024-05-26T09:10:33-07:00
 +++
 
-Thénardier was not mistaken. The man was sitting there, and letting
-Cosette get somewhat rested.
+This is the first paragraph.
 
 <!--more-->
 
-The inn-keeper walked round the brushwood and presented himself
-abruptly to the eyes of those whom he was in search of.
+This is the second paragraph.
 {{< /code >}}
 
-When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the content summary.
+When using the Emacs Org Mode [content format], use a `# more` divider to indicate the end of the summary.
 
 [content format]: /content-management/formats/
 
@@ -48,46 +47,44 @@ When using the Emacs Org Mode [content format], use a `# more` divider to indica
 
 Use front matter to define a summary independent of content.
 
-{{< code file=content/sample.md >}}
+{{< code file=content/example.md >}}
 +++
 title: 'Example'
 date: 2024-05-26T09:10:33-07:00
-summary: 'Learn more about _Les Misérables_ by Victor Hugo.'
+summary: 'This summary is independent of the content.'
 +++
 
-Thénardier was not mistaken. The man was sitting there, and letting
-Cosette get somewhat rested. The inn-keeper walked round the
-brushwood and presented himself abruptly to the eyes of those whom
-he was in search of.
+This is the first paragraph.
+
+This is the second paragraph.
 {{< /code >}}
 
 ## Automatic summary
 
-If you have not defined the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration.
+If you do not define the summary manually or in front matter, Hugo automatically defines the summary based on the [`summaryLength`] in your site configuration.
 
 [`summaryLength`]: /getting-started/configuration/#summarylength
 
-{{< code file=content/sample.md >}}
+{{< code file=content/example.md >}}
 +++
 title: 'Example'
 date: 2024-05-26T09:10:33-07:00
 +++
 
-Thénardier was not mistaken. The man was sitting there, and letting
-Cosette get somewhat rested. The inn-keeper walked round the
-brushwood and presented himself abruptly to the eyes of those whom
-he was in search of.
+This is the first paragraph.
+
+This is the second paragraph.
+
+This is the third paragraph.
 {{< /code >}}
 
-For example, with a `summaryLength` of 10, the automatic summary will be:
+For example, with a `summaryLength` of 7, the automatic summary will be:
 
-```text
-Thénardier was not mistaken. The man was sitting there, and letting
-Cosette get somewhat rested.
+```html
+<p>This is the first paragraph.</p>
+<p>This is the second paragraph.</p>
 ```
 
-Note that the `summaryLength` is an approximate number of words.
-
 ## Comparison
 
 Each summary type has different characteristics:
@@ -115,3 +112,18 @@ Render the summary in a template by calling the [`Summary`] method on a `Page` o
   </div>
 {{ end }}
 ```
+
+## Alternative
+
+Instead of calling the `Summary` method on a `Page` object, use the [`strings.Truncate`] function for granular control of the summary length. For example:
+
+[`strings.Truncate`]: /functions/strings/truncate/
+
+```go-html-template
+{{ range site.RegularPages }}
+  <h2><a href="{{ .RelPermalink }}">{{ .LinkTitle }}</a></h2>
+  <div class="summary">
+    {{ .Content | strings.Truncate 42 }}
+  </div>
+{{ end }}
+```
diff --git a/content/en/content-management/urls.md b/content/en/content-management/urls.md
index e3370f956..0f1d93c63 100644
--- a/content/en/content-management/urls.md
+++ b/content/en/content-management/urls.md
@@ -43,11 +43,45 @@ https://example.org/posts/my-first-post/
 
 Set the `url` in front matter to override the entire path. Use this with either regular pages or section pages.
 
+{{% note %}}
+Hugo does not sanitize the `url` front matter field, allowing you to generate:
+
+- File paths that contain characters reserved by the operating system. For example, file paths on Windows may not contain any of these [reserved characters]. Hugo throws an error if a file path includes a character reserved by the current operating system.
+- URLs that contain disallowed characters. For example, the less than sign (`<`) is not allowed in a URL.
+
+[reserved characters]: https://learn.microsoft.com/en-us/windows/win32/fileio/naming-a-file#naming-conventions
+{{% /note %}}
+
+If you set both `slug` and `url` in front matter, the `url` value takes precedence.
+
+#### Include a colon
+
+{{< new-in 0.136.0 >}}
+
+If you need to include a colon in the  `url` front matter field, escape it with backslash characters. Use one backslash if you wrap the string within single quotes, or use two backslashes if you wrap the string within double quotes. With YAML front matter, use a single backslash if you omit quotation marks.
+
+For example, with this front matter:
+
+{{< code-toggle file=content/example.md fm=true >}}
+title: Example
+url: "my\\:example"
+{{< /code-toggle >}}
+
+The resulting URL will be:
+
+```text
+https://example.org/my:example/
+```
+
+As described above, this will fail on Windows because the colon (`:`) is a reserved character.
+
+#### File extensions
+
 With this front matter:
 
 {{< code-toggle file=content/posts/post-1.md fm=true >}}
 title = 'My First Article'
-url = '/articles/my-first-article'
+url = 'articles/my-first-article'
 {{< /code-toggle >}}
 
 The resulting URL will be:
@@ -60,7 +94,7 @@ If you include a file extension:
 
 {{< code-toggle file=content/posts/post-1.md fm=true >}}
 title = 'My First Article'
-url = '/articles/my-first-article.html'
+url = 'articles/my-first-article.html'
 {{< /code-toggle >}}
 
 The resulting URL will be:
@@ -69,12 +103,11 @@ The resulting URL will be:
 https://example.org/articles/my-first-article.html
 ```
 
-In a monolingual site, a `url` value with or without a leading slash is relative to the `baseURL`.
+#### Leading slashes
 
-In a multilingual site:
+With monolingual sites, `url` values with or without a leading slash are relative to the [`baseURL`]. With multilingual sites, `url` values with a leading slash are relative to the `baseURL`, and  `url` values without a leading slash are relative to the `baseURL` plus the language prefix.
 
-- A `url` value with a leading slash is relative to the `baseURL`.
-- A `url` value without a leading slash is relative to the `baseURL` plus the language prefix.
+[`baseURL`]: /getting-started/configuration/#baseurl
 
 Site type|Front matter `url`|Resulting URL
 :--|:--|:--
@@ -83,13 +116,11 @@ monolingual|`about`|`https://example.org/about/`
 multilingual|`/about`|`https://example.org/about/`
 multilingual|`about`|`https://example.org/de/about/`
 
-If you set both `slug` and `url` in front matter, the `url` value takes precedence.
-
 #### Permalinks tokens in front matter
 
 {{< new-in "0.131.0" >}}
 
-You can also use [Permalinks tokens](#tokens) in the `url` front matter. This is typically used in `cascade` sections:
+You can also use [tokens](#tokens) when setting the `url` value. This is typically used in `cascade` sections:
 
 {{< code-toggle file=content/foo/bar/_index.md fm=true >}}
 title ="Bar"
@@ -246,9 +277,7 @@ public/
 
 #### Tokens
 
-Use these tokens when defining the URL pattern. These can both be used in the `permalinks` configuration and in the front matter [url](#permalinks-tokens-in-front-matter).
-
-`:filename`
+Use these tokens when defining the URL pattern. You can also use these tokens when setting the [`url`](#permalinks-tokens-in-front-matter) value in front matter.
 
 `:year`
 : The 4-digit year as defined in the front matter `date` field.
@@ -313,6 +342,14 @@ By default, Hugo produces pretty URLs. To generate ugly URLs, change your site c
 uglyURLs = true
 {{< /code-toggle >}}
 
+You can also enable uglyURLs by section. For example, with a site that contains sections for books and films:
+
+{{< code-toggle file=hugo >}}
+[uglyURLs]
+books = true
+films = false
+{{< /code-toggle >}}
+
 ### Post-processing
 
 Hugo provides two mutually exclusive configuration options to alter URLs _after_ it renders a page.