Question
Jekyll timezone configuration: evaluating per‑post override support
Ira Orbit
0 reputation · 26 Jul 2024, 19:45 UTC
97.9K views1
Loading…
0 reputation · 26 Jul 2024, 19:45 UTC
Jekyll currently applies a single timezone—set via timezone in _config.yml or the TZ environment variable—to all dates parsed from front matter and formatted by the Liquid date filter. There is no built‑in way for an individual post or page to specify a different zone, and the project has not decided whether a front‑matter timezone: key should be honored.
Introducing per‑post timezone overrides would let authors display dates in local zones without manual offset calculations, but it raises questions about backward compatibility, especially after Jekyll 4.2 began treating an unrecognized timezone value as a hard error instead of silently falling back to UTC. Any change must also consider variations in Ruby’s timezone database across versions.
Should Jekyll recognize a timezone key in a page’s front matter and apply it only to that page’s Liquid date output? What impact would this have on existing sites that rely on the global setting? How should Jekyll handle invalid or unsupported timezone values supplied in front matter?
No—stable Jekyll does not recognize a timezone key in a page's front matter, and it should not silently begin doing so. The global timezone in _config.yml or the process TZ remains the single source of truth for parsing and formatting dates. If maintainers add a per-document override, it must be explicit, documented, and limited to Liquid date rendering for that document only.
Confirmed: front matter supplies document data and the raw date value, but the zone applied to that value comes from site configuration or the environment. There is no supported mechanism today for a single post to opt into a different zone.
Likely explanation for the proposal: authors want local display strings without manual offset arithmetic. The missing capability is a presentation-layer zone, not a change to how post.date is stored, sorted, or emitted in machine-readable feeds.
An absent key changes nothing. A present key would alter only that page's Liquid output if the feature is implemented. However, some sites may already use timezone in front matter as unrelated custom metadata; honoring it would silently change their output. To limit risk, scope the override to the Liquid date filter. Do not let it affect site.time, post.date, permalinks, collection order, feeds, or sitemaps, because those feed URLs, ordering, caching, SEO, and downstream consumers.
Accept only IANA zone names that the Ruby runtime can resolve—prefer Area/Location names such as America/New_York over abbreviations like EST. On an invalid or unsupported front-matter value, fail the build with an error that names the file and the key. This mirrors strict global timezone handling and avoids silently falling back to UTC or the global zone, which would hide author error. Because Ruby's timezone database varies by version and platform, pin Ruby and tzdata in CI and test IANA names across supported Rubies.
To confirm current behavior on your version, build a fixture site with global timezone: UTC and two posts sharing one front-matter date. Add timezone: America/New_York to one post and inspect rendered Liquid date, post.date, site.time, the feed, the sitemap, and collection order. Then set an invalid front-matter zone and run jekyll build to see whether it errors, falls back, or ignores the value.
Which exact Jekyll version are you targeting? Timezone validation and front-matter handling are version-sensitive, and the recommendation changes if you are on a release where unrecognized global zones already hard-error.
Use comments to ask for clarification. Post a solution as an answer.
No question comments on this page.
jekyll