Question
Hugo timeZone configuration and UTC date conversion behavior
Cig River
0 reputation · 07 Apr 2021, 00:43 UTC
72.3K views1
Loading…
0 reputation · 07 Apr 2021, 00:43 UTC
Hugo uses the timeZone parameter in the site configuration to define the target time zone for date rendering. While this global setting typically governs how .Date is processed in templates, the interaction between front matter offsets and this configuration can create inconsistencies.
When a content file specifies a date in RFC 3339 format with an explicit UTC offset, it may override the global timeZone setting. This behavior complicates the goal of maintaining a uniform regional timestamp across a site when source files originate from different time zones or use UTC by default.
Does the timeZone configuration force conversion for all dates regardless of the offset provided in the front matter? If not, what is the documented priority between the global configuration and the individual file's time zone offset during the build process?
34775 reputation · 07 Apr 2021, 08:08 UTC
Hugo’s timeZone setting does not override an explicit RFC 3339 offset that is already parsed from a file’s front matter. The value in the front matter determines the absolute point in time; the global timeZone only changes how that point is displayed when a date function is called in a template.
hugo2023-10-04T00:00:00-05:00 is converted to a UTC instant when the page is read..Date, now, or date will format that instant in the zone supplied by timeZone (or the system zone if timeZone is empty).config.toml:
timeZone = \"America/New_York\"
UTC method in the template:
{{ .Date.UTC.Format \"2006-01-02 15:04 MST\" }}hugo --printInfoDo you need to keep the front‑matter offsets for archival purposes, or do you want every page to display in the same local time? That choice determines whether you rely on timeZone or on .UTC in the template.
Use comments to ask for clarification. Post a solution as an answer.
5,940 reputation · 07 Apr 2021, 01:49 UTC
One nuance in the existing answer: the timeZone setting does not automatically convert a date that already carries an explicit RFC 3339 offset when you format it. Hugo parses such dates into a time.Time that retains the original offset as a fixed zone, so .Date.Format renders in that offset, not in the site’s timeZone. The timeZone config instead sets the default location for offset-less dates and for now. To force a uniform display zone, convert explicitly in the template, e.g. {{ .Date.In (time.LoadLocation "America/New_York").Format "..." }} or {{ .Date.Local.Format "..." }} if Hugo has set time.Local to your configured zone. Verify with two front matter dates using different offsets and compare the rendered output under a single timeZone setting.