time.Format
- Syntax
- time.Format LAYOUT INPUT
- Returns
- string
- Alias
- dateFormat
Usage
The time.Format function returns the given date/time as a formatted and localized string. Set the LAYOUT to a layout string or a localization token.
The INPUT can be a time.Time value, such as one of the four predefined front matter dates or a value returned by the time.AsTime function, or a string. A string must be a parsable representation of a date/time value, such as one of these:
| Format | Time zone offset |
|---|---|
2023-10-15T13:18:50-07:00 | -07:00 |
2023-10-15T13:18:50-0700 | -07:00 |
2023-10-15T13:18:50Z | +00:00 |
2023-10-15T13:18:50 | None |
2023-10-15 | None |
15 Oct 2023 | None |
The last three examples do not include a time zone offset.
If the INPUT is a string with a time zone offset, the function uses that offset. If the INPUT is a string without a time zone offset, the function uses the time zone set by the timeZone setting in your project configuration, falling back to Etc/UTC, and the time zone determines the offset for that date. To use a different time zone, convert the string with the time.AsTime function first, passing the time zone as the second argument.
Layout string
Format a time.Time value based on Go’s reference time:
Mon Jan 2 15:04:05 MST 2006Create a layout string using these components:
| Description | Valid components |
|---|---|
| Year | "2006" "06" |
| Month | "Jan" "January" "01" "1" |
| Day of the week | "Mon" "Monday" |
| Day of the month | "2" "_2" "02" |
| Day of the year | "__2" "002" |
| Hour | "15" "3" "03" |
| Minute | "4" "04" |
| Second | "5" "05" |
| AM/PM mark | "PM" |
| Time zone abbreviation | "MST" |
| Time zone offsets | "-0700" "-07:00" "-07" "-070000" "-07:00:00" |
Replace the sign in the layout string with a Z to print Z instead of the offset when the offset is zero.
| Description | Valid components |
|---|---|
| Time zone offsets | "Z0700" "Z07:00" "Z07" "Z070000" "Z07:00:00" |
{{ $t := "2023-01-27T23:44:58-08:00" }}
{{ $t = time.AsTime $t }}
{{ $t = $t.Format "Jan 02, 2006 3:04 PM Z07:00" }}
{{ $t }} → Jan 27, 2023 11:44 PM -08:00The MST component prints the abbreviation of the date/time’s time zone, such as PST or CET. If the date/time has a time zone offset but no time zone, the component prints the offset instead, such as -0800. Whether a date/time created from a string with an offset has a time zone can depend on the time zone of the system running Hugo.
The time.Format function handles a zero offset differently, as described in the warning under Localization.
When the layout string includes the name of a month or a day of the week, the function localizes the name for the current language and region. The function does not localize other parts of the result, such as the order of the components or the PM mark. To localize the entire date/time, use a localization token.
Localization
Set the LAYOUT to one of the tokens below to format and localize the entire date/time, including the order of its components, for the current language and region.
Localization of dates, currencies, numbers, and percentages is performed by the bep/golocales package. Hugo determines the locale using the locale configuration setting, falling back to the language key itself. The resolved value must be a locale supported by the package.
The tables below show the result of each token, given the date/time 2023-01-27T23:44:58-08:00, when you build your project on a system set to the America/Los_Angeles time zone.
With the locale set to en-US:
| Token | Result |
|---|---|
:date_full | Friday, January 27, 2023 |
:date_long | January 27, 2023 |
:date_medium | Jan 27, 2023 |
:date_short | 1/27/23 |
:time_full | 11:44:58 pm Pacific Standard Time |
:time_long | 11:44:58 pm PST |
:time_medium | 11:44:58 pm |
:time_short | 11:44 pm |
With the locale set to de-DE:
| Token | Result |
|---|---|
:date_full | Freitag, 27. Januar 2023 |
:date_long | 27. Januar 2023 |
:date_medium | 27.01.2023 |
:date_short | 27.01.23 |
:time_full | 23:44:58 Nordamerikanische Westküsten-Normalzeit |
:time_long | 23:44:58 PST |
:time_medium | 23:44:58 |
:time_short | 23:44 |
The time zone name in the result of the :time_full and :time_long tokens, and of the MST component of a layout string, depends on the time zone of the date/time:
- If the date/time has a time zone, the result includes the name of that time zone. This applies to a string without a time zone offset, a front matter date without a time zone offset, and a value returned by the
time.Infunction. - If the date/time has a time zone offset but no time zone, the result depends on the time zone of the system running Hugo. This applies to a string with a time zone offset and a front matter date with a time zone offset. If the offset matches the offset of the system’s time zone on that date, the result includes the name of the system’s time zone. Otherwise, if the offset is zero, the result includes
UTC, unless theINPUTis a string with a+00:00offset. In all other cases, the:time_fulland:time_longtokens omit the time zone name, and theMSTcomponent returns the offset, such as-0800. For example, if you build your project on a system set to theUTCtime zone, the:time_longtoken in the tables above returns11:44:58 pminstead of11:44:58 pm PST.
To get the same result on every system, pass the INPUT to the time.In function before formatting it, such as time.In "America/Los_Angeles" $t. Convert a string with the time.AsTime function first.
Arguments
LAYOUT- (
string) A layout string or a localization token. INPUT- (
time.Timeorstring) The date/time value. Use atime.Timevalue, such as theDateof a page or a value returned by thetime.AsTimefunction, or a parsable string representation of a date/time value, such as2023-10-15T13:18:50-07:00. You can also pass a custom date parameter from JSON, TOML, or YAML front matter, quoted or unquoted, without converting it first.
Examples
{{ $t := time "2023-10-15T13:18:50-07:00" }}
{{ time.Format "2 Jan 2006" $t }} → 15 Oct 2023Formatting a string representation of a date/time value:
{{ time.Format "January 2, 2006" "15 Oct 2023" }} → October 15, 2023Formatting with a localization token, with the locale set to en-US:
{{ time.Format ":date_medium" "2023-01-27T23:44:58-08:00" }} → Jan 27, 2023