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 or a parsable string representation of a date/time value, such as one of these:
| Format | Time zone |
|---|---|
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 three examples are not fully qualified, and default to the Etc/UTC time zone.
If the INPUT is a string without a time zone offset, the function uses the timeZone setting in your project configuration, falling back to the Etc/UTC time zone. 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 offsets | "-0700" "-07:00" "-07" "-070000" "-07:00:00" |
Replace the sign in the layout string with a Z to print Z instead of an offset for the UTC zone.
| 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:00Strings such as PST and CET are not time zones. They are time zone abbreviations.
Strings such as -07:00 and +01:00 are not time zones. They are time zone offsets.
A time zone is a geographic area with the same local time. For example, the time zone abbreviated by PST and PDT (depending on Daylight Savings Time) is America/Los_Angeles.
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.
Localization
Set the LAYOUT to one of the tokens below to format the date/time 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 result of the :time_full and :time_long tokens depends on the time zone of the system running Hugo. When the INPUT is a time.Time value or a string with a time zone offset, the function keeps the offset but not the time zone. If the offset is not zero and does not match the offset of the system’s time zone on that date, the result does not include a time zone name. For example, if you build your project on a system set to the UTC time zone, the :time_long token in the tables above returns 11:44:58 pm instead of 11:44:58 pm PST.
To get the same result on every system, set the system’s time zone to the time zone of your date/time values. On Linux and macOS, you can set the TZ environment variable when you build your project, such as TZ=America/Los_Angeles hugo build.
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