Hugo vs Jekyll Front Matter

Both wrap metadata in YAML between --- lines — but the rules they expect differ in ways that break a build.

The shared core

Both generators read a YAML block at the top of a Markdown file. The syntax is identical, so a valid block for one is usually valid for the other:

---
title: My Post
date: 2026-08-21
tags:
  - yaml
  - ssg
---

Where they diverge

Required keys

Hugo expects at least a title (and usually a date) for regular content; without them, list pages and permalinks can misbehave. Jekyll is far more lenient — a file with no front matter at all is simply treated as plain content.

Date handling

Both accept ISO dates such as 2026-08-21. Hugo is stricter: it uses the date for sorting and permalink generation, so malformed dates cause real problems. Jekyll is more forgiving and will often parse looser values.

Taxonomies

Hugo has first-class taxonomies (tags and categories are configured in the site config and drive listing pages). Jekyll treats tags as a simple list unless a plugin adds behaviour.

Custom variables

Both let you add arbitrary keys and read them in templates. The difference is convention: Hugo documents a clear set of reserved keys; Jekyll leaves almost everything to the theme.

A Hugo example

---
title: "Deploying with Hugo"
date: 2026-08-21T10:00:00Z
draft: false
tags: [yaml, hugo]
categories: [guides]
---

A Jekyll example

---
title: Deploying with Jekyll
date: 2026-08-21
layout: post
tags: [yaml, jekyll]
---

Validate before you build

A single bad line in front matter fails the whole site build. Paste the file into the YAML frontmatter validator to confirm the block parses — it ignores the page body and reports the exact line of any error. Everything runs in your browser.

See also the general front matter guide and the Obsidian front matter notes.

FAQ

Is front matter the same in Hugo and Jekyll?

Both use YAML between --- delimiters, but Hugo requires a title and a date for standard content and has first-class taxonomies, while Jekyll is more lenient and treats most keys as arbitrary page variables.

How do Hugo and Jekyll handle dates in front matter?

Both accept ISO dates such as 2026-08-21, but Hugo is strict about date formats for sorting and permalink generation, whereas Jekyll is more forgiving and will often parse looser values.

Do tags work the same way?

Syntactically yes — both use a YAML list. Semantically, Hugo has explicit taxonomies (tags and categories) configured in config, while Jekyll treats tags as a simple list unless plugins add behaviour.

Keep reading