From 1377ed4deb43fb2491f37e588c647bb7b9f2b271 Mon Sep 17 00:00:00 2001 From: Joe Mooring Date: Sat, 5 Oct 2024 15:57:06 -0700 Subject: [PATCH] Clarify date parsing --- .cspell.json | 4 +++ content/en/content-management/front-matter.md | 23 +++++++++++--- content/en/functions/time/AsTime.md | 31 +++++++------------ content/en/functions/time/Format.md | 18 ++++++++--- .../_common/parsable-date-time-strings.md | 16 +++++----- content/en/getting-started/configuration.md | 7 +++-- 6 files changed, 60 insertions(+), 39 deletions(-) diff --git a/.cspell.json b/.cspell.json index 01d248e25..6596a160c 100644 --- a/.cspell.json +++ b/.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", diff --git a/content/en/content-management/front-matter.md b/content/en/content-management/front-matter.md index aeb771a19..e73696957 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/ @@ -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 diff --git a/content/en/functions/time/AsTime.md b/content/en/functions/time/AsTime.md index 23e5304a5..70b2bd1f3 100644 --- a/content/en/functions/time/AsTime.md +++ b/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: +```go-html-template +{{ time.AsTime "15 Oct 2023" "America/Los_Angeles" }} +``` -- 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 - - {{< 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/ diff --git a/content/en/functions/time/Format.md b/content/en/functions/time/Format.md index 74384959b..b9db6905b 100644 --- a/content/en/functions/time/Format.md +++ b/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" %}} diff --git a/content/en/functions/time/_common/parsable-date-time-strings.md b/content/en/functions/time/_common/parsable-date-time-strings.md index a38b9983e..6d1633a6f 100644 --- a/content/en/functions/time/_common/parsable-date-time-strings.md +++ b/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. diff --git a/content/en/getting-started/configuration.md b/content/en/getting-started/configuration.md index b5b2ddd36..df6309eb3 100644 --- a/content/en/getting-started/configuration.md +++ b/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/