blogs/hugo
1
0
Fork 0
mirror of https://github.com/gohugoio/hugo.git synced 2026-08-24 15:28:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Clarify date parsing

Browse Source
This commit is contained in:
Joe Mooring
2024-10-05 15:57:06 -07:00
committed by GitHub
parent e19fb80431
commit 1377ed4deb
6 changed files with 60 additions and 39 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.cspell.json
+4
View File
@@ -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
+18 -5
View File
@@ -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
+12 -19
View File
@@ -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/
content/en/functions/time/Format.md
+13 -5
View File
@@ -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
+8 -8
View File
@@ -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
+5 -2
View File
@@ -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/