Clarify date parsing

.cspell.json

@@ -85,6 +85,7 @@
     "stringifier",
     "struct",
     "toclevels",
+    "unpublishdate",
     "zgotmplz",
     "# ----------------------------------------------------------------------",
     "# cspell: ignore foreign language words",
@@ -129,6 +130,7 @@
     "Samsa",
     "Stucki",
     "Thénardier",
+    "WASI",
     "# ----------------------------------------------------------------------",
     "# cspell: ignore operating systems and software packages",
     "# ----------------------------------------------------------------------",
@@ -158,10 +160,12 @@
     "achristie",
     "ddmaurier",
     "dring",
+    "fleqn",
     "inor",
     "jausten",
     "jdoe",
     "jsmith",
+    "leqno",
     "milli",
     "rgba",
     "rsmith",

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/
 
@@ -141,7 +142,7 @@ lang
 
 ###### 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/
 
@@ -201,7 +202,7 @@ 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/
 
@@ -444,3 +445,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

content/en/functions/time/AsTime.md

@@ -21,41 +21,34 @@ toc: true
 Hugo provides [functions] and [methods] to format, localize, parse, compare, and manipulate date/time values. Before you can do any of these with string representations of date/time values, you must first convert them to [`time.Time`] values using the `time.AsTime` function.
 
 ```go-html-template
-{{ $t := "2023-10-15T14:20:28-07:00" }}
-{{ time.AsTime $t }} → 2023-10-15 14:20:28 -0700 PDT (time.Time)
+{{ $t := "2023-10-15T13:18:50-07:00" }}
+{{ time.AsTime $t }} → 2023-10-15 13:18:50 -0700 PDT (time.Time)
 ```
 
 ## Parsable strings
 
-As shown above, the first argument must be a *parsable* string representation of a date/time value. For example:
+As shown above, the first argument must be a parsable string representation of a date/time value. For example:
 
 {{% include "functions/time/_common/parsable-date-time-strings.md" %}}
 
-## Time zones
+To override the default time zone, set the [`timeZone`] in your site configuration or provide a second argument to the `time.AsTime` function. For example:
 
-When the parsable string does not contain a time zone offset, you can do either of the following to assign a time zone other than Etc/UTC:
-
-- Provide a second argument to the `time.AsTime` function
-
-  ```go-html-template
-  {{ time.AsTime "15 Oct 2023" "America/Chicago" }}
-  ```
-
-- Set the default time zone in your site configuration
+```go-html-template
+{{ time.AsTime "15 Oct 2023" "America/Los_Angeles" }}
+```
 
-  {{< code-toggle file=hugo >}}
-  timeZone = 'America/New_York'
-  {{< /code-toggle >}}
+The list of valid time zones may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database].
 
 The order of precedence for determining the time zone is:
 
 1. The time zone offset in the date/time string
-2. The time zone provide as the second argument to the `time.AsTime` function
+2. The time zone provided as the second argument to the `time.AsTime` function
 3. The time zone specified in your site configuration
+4. The `Etc/UTC` time zone
 
-The list of valid time zones may be system dependent, but should include `UTC`, `Local`, or any location in the [IANA Time Zone database].
 
+[IANA Time Zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 [`time.Time`]: https://pkg.go.dev/time#Time
+[`timeZone`]: https://gohugo.io/getting-started/configuration/#timezone
 [functions]: /functions/time/
-[iana time zone database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 [methods]: /methods/time/

content/en/functions/time/Format.md

@@ -19,21 +19,29 @@ toc: true
 Use the `time.Format` function with `time.Time` values:
 
 ```go-html-template
-{{ $t := time.AsTime "2023-02-27T23:44:58-08:00" }}
-{{ time.Format "2 Jan 2006" $t }} → 27 Feb 2023
+{{ $t := time.AsTime "2023-10-15T13:18:50-07:00" }}
+{{ time.Format "2 Jan 2006" $t }} → 15 Oct 2023
 ```
 
-Or use `time.Format` with a *parsable* string representation of a date/time value:
+Or use `time.Format` with a parsable string representation of a date/time value:
 
 ```go-html-template
-{{ $t := "27 Feb 2023" }}
-{{ time.Format "January 2, 2006" $t }} → February 27, 2023
+{{ $t := "15 Oct 2023" }}
+{{ time.Format "January 2, 2006" $t }} → October 15, 2023
 ```
 
 Examples of parsable string representations:
 
 {{% include "functions/time/_common/parsable-date-time-strings.md" %}}
 
+To override the default time zone, set the [`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
+
+[`timeZone`]: https://gohugo.io/getting-started/configuration/#timezone
+
 ## Layout string
 
 {{% include "functions/_common/time-layout-string.md" %}}

content/en/functions/time/_common/parsable-date-time-strings.md

@@ -2,13 +2,13 @@
 # Do not remove front matter.
 ---
 
-String representation|Time zone
+Format|Time zone
 :--|:--
-2023-10-15T14:20:28-07:00|America/Los_Angeles
-2023-10-15T13:18:50-0700|America/Los_Angeles
-2023-10-15T13:18:50Z|Etc/UTC
-2023-10-15T13:18:50|Etc/UTC
-2023-10-15|Etc/UTC
-15 Oct 2023|Etc/UTC
+`2023-10-15T13:18:50-07:00`|`America/Los_Angeles`
+`2023-10-15T13:18:50-0700`|`America/Los_Angeles`
+`2023-10-15T13:18:50Z`|`Etc/UTC`
+`2023-10-15T13:18:50`|Default is `Etc/UTC`
+`2023-10-15`|Default is `Etc/UTC`
+`15 Oct 2023`|Default is `Etc/UTC`
 
-The last four examples are not fully qualified. Without a time zone offset, the time zone is set to Etc/UTC (Coordinated Universal Time).
+The last three examples are not fully qualified, and default to the `Etc/UTC` time zone.

content/en/getting-started/configuration.md

@@ -520,7 +520,11 @@ See [module configuration](/hugo-modules/configuration/#module-configuration-imp
 
 ###### timeZone
 
-(`string`) The time zone (or location), e.g. `Europe/Oslo`, used to parse front matter dates without such information and in the [`time`] function. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone database](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones).
+(`string`) The time zone used to parse dates without time zone offsets, including front matter date fields and values passed to the [`time.AsTime`] and [`time.Format`] template functions. The list of valid values may be system dependent, but should include `UTC`, `Local`, and any location in the [IANA Time Zone Database]. For example, `America/Los_Angeles` and `Europe/Oslo` are valid time zones.
+
+[`time.AsTime`]: /functions/time/astime/
+[`time.Format`]: /functions/time/format/
+[IANA Time Zone Database]: https://en.wikipedia.org/wiki/List_of_tz_database_time_zones
 
 ###### title
 
@@ -937,7 +941,6 @@ If this is not set, Hugo will use, in order of preference:
 
 If you want to know the current value of `cacheDir`, you can run `hugo config`, e.g: `hugo config | grep cachedir`.
 
-[`time`]: /functions/time/astime/
 [`.Site.Params`]: /method/site/params/
 [directory structure]: /getting-started/directory-structure/
 [lookup order]: /templates/lookup-order/