Jekyll Front Matter: The Complete Guide

Front matter is how Jekyll knows what to do with a file. Without it, Jekyll treats a file as a static asset and copies it unchanged. With it, Jekyll processes the file through its template engine, applies a layout, and builds a page with all the data you specified.

Understanding front matter is foundational to using Jekyll effectively. This guide covers everything from basic syntax to advanced defaults.

What is front matter?

Front matter is a block of YAML at the top of a file, enclosed between triple-dashed lines:

---
layout: post
title: "My First Post"
date: 2026-07-29
---

Content goes here.

The triple dashes are required — both opening and closing. Jekyll strips the front matter block before rendering the content and makes all the variables available in your Liquid templates.

Any file in a Jekyll site that has front matter (even empty front matter --- ---) is processed by Jekyll. Files without front matter are copied as-is.

YAML basics

Front matter uses YAML (YAML Ain’t Markup Language). You only need to know a handful of YAML patterns to write effective front matter.

Strings:

title: "My Post Title"
title: My Post Title        # quotes are optional for simple strings
description: "A post about Jekyll front matter — the basics and beyond."

Numbers:

nav_order: 3
weight: 10

Booleans:

published: true
featured: false
toc: true

Lists (arrays):

tags:
  - jekyll
  - tutorial
  - yaml

# Or inline:
tags: [jekyll, tutorial, yaml]

Nested objects:

author:
  name: Marcus Webb
  email: marcus@example.com
  twitter: marcuswebb

Multiline strings:

description: >
  This is a long description that spans
  multiple lines but will be joined into
  a single paragraph.

excerpt: |
  This preserves
  line breaks
  exactly.

Built-in Jekyll front matter variables

Jekyll recognises several variable names and uses them specially:

layout

Specifies which layout file from _layouts/ to use:

layout: post        # uses _layouts/post.html
layout: page        # uses _layouts/page.html
layout: default     # uses _layouts/default.html
layout: none        # no layout — render content only

If omitted, Jekyll uses no layout (renders content only). Most files should specify a layout.

title

The page title. Available as Jekyll Front Matter: The Complete Guide in templates and used by jekyll-seo-tag for the <title> element:

title: "Jekyll Front Matter: The Complete Guide"

date

For posts in _posts/, the date is normally part of the filename (2026-07-29-my-post.md). You can override or supplement it with a front matter date:

date: 2026-07-29
date: 2026-07-29 14:30:00 +0100    # with time and timezone

The date variable sets page.date, which is used for sorting posts and for display in templates.

published

Controls whether Jekyll includes the page in the build output:

published: false    # page is excluded from build
published: true     # page is included (default)

Drafts in _drafts/ are automatically excluded unless you run jekyll serve --drafts.

permalink

Overrides Jekyll’s default URL for the page:

permalink: /about/
permalink: /blog/:year/:month/:title/
permalink: /themes/minimal/

Available :placeholders for posts: :year, :month, :day, :title, :categories, :slug.

categories and tags

Categorise and tag your content:

categories: Tutorial
categories:
  - Tutorial
  - Jekyll

tags: [front-matter, yaml, jekyll]

categories affects the default URL of posts (/tutorial/2026/07/29/my-post/). tags do not affect URLs.

excerpt

By default, Jekyll uses the first paragraph of a post as its excerpt. Override with:

excerpt: "A short custom summary for use in post listings and meta descriptions."

last_modified_at

Used by jekyll-seo-tag and jekyll-sitemap to set the <lastmod> value:

last_modified_at: 2026-07-29

Custom front matter variables

Any variable you add to front matter becomes available in your templates as page.variable_name:

---
layout: post
title: "My Post"
author: Marcus Webb
reading_time: 8
featured_image: /assets/images/hero.webp
show_newsletter: true
difficulty: beginner
---

In your templates:

<p>By {{ page.author }} · {{ page.reading_time }} min read</p>

{% if page.featured_image %}
<img src="{{ page.featured_image }}" alt="{{ page.title }}">
{% endif %}

{% if page.show_newsletter %}
  {% include newsletter-form.html %}
{% endif %}

This pattern is powerful — you can add any metadata to a page and use it anywhere in your templates without touching layout files.

Front matter in different file types

Posts (`_posts/`)

---
layout: post
title: "How to Install a Jekyll Theme"
description: "Step-by-step guide to installing any Jekyll theme in under 10 minutes."
date: 2026-07-29
last_modified_at: 2026-07-29
image: /assets/images/blog/install-jekyll-theme.webp
author: Marcus Webb
category: Tutorial
tags: [jekyll, themes, tutorial]
featured: false
toc: true
---

Pages (`_pages/` or root)

---
layout: page
title: "About JekyllHub"
description: "The story behind JekyllHub — a marketplace for Jekyll themes."
permalink: /about/
nav_order: 4
---

Collection items (`_themes/`, `_authors/`, etc.)

---
layout: theme
title: "Minimal Mistakes"
github_url: https://github.com/mmistakes/minimal-mistakes
stars: 12800
price: 0
category: Blog
tags: [responsive, dark-mode, sidebar]
---

Layouts and includes

Layouts and includes can also have front matter, but it is rarely used. One exception: layout inheritance.

---
layout: default    # This layout itself uses another layout
---

Front matter defaults

Repeating the same front matter on every post is tedious. Jekyll’s defaults feature lets you set front matter values globally in _config.yml:

# _config.yml
defaults:
  # Default for all posts
  - scope:
      path: ""
      type: posts
    values:
      layout: post
      author: Marcus Webb
      toc: true
      featured: false

  # Default for all pages
  - scope:
      path: ""
      type: pages
    values:
      layout: page

  # Default for a specific directory
  - scope:
      path: "_themes"
      type: themes
    values:
      layout: theme

  # Default for files matching a path pattern
  - scope:
      path: "guides/**"
    values:
      layout: guide
      show_sidebar: true

With these defaults set, you do not need to specify layout: post or author: Marcus Webb on every post — Jekyll applies them automatically. Front matter in the file still overrides defaults.

Specificity: More specific scopes override less specific ones. A post-level default overrides a site-wide default. Front matter in the file overrides both.

Accessing front matter in templates

All front matter variables are available in Liquid templates:

<!-- In the layout file -->
<h1>{{ page.title }}</h1>
<p>{{ page.description }}</p>
<time>{{ page.date | date: "%B %-d, %Y" }}</time>

<!-- Conditional display -->
{% if page.toc %}
  {% include toc.html %}
{% endif %}

<!-- Iteration over arrays -->
{% for tag in page.tags %}
  <span class="tag">{{ tag }}</span>
{% endfor %}

<!-- Nested objects -->
{{ page.author.name }}
{{ page.author.twitter }}

Accessing front matter from other pages

You can loop through all pages or posts and access their front matter:

<!-- List all posts with their metadata -->
{% for post in site.posts %}
  <article>
    <h2><a href="{{ post.url }}">{{ post.title }}</a></h2>
    <p>{{ post.description }}</p>
    {% if post.featured %}
      <span class="badge">Featured</span>
    {% endif %}
  </article>
{% endfor %}

<!-- Filter by front matter value -->
{% assign featured_posts = site.posts | where: "featured", true %}
{% for post in featured_posts %}
  <a href="{{ post.url }}">{{ post.title }}</a>
{% endfor %}

Common front matter patterns

---
layout: page
title: "Thank You"
permalink: /thank-you/
sitemap: false
---

Overriding the excerpt

---
layout: post
title: "My Post"
excerpt: "This custom excerpt appears in post listings and meta descriptions instead of the first paragraph."
---

---
layout: post
title: "My Post"
image: /assets/images/blog/my-post.webp
---

With jekyll-seo-tag, image is automatically used as the Open Graph image.

Controlling the canonical URL

---
layout: post
title: "My Post"
canonical_url: "https://original-source.com/my-post/"
---

Useful if you are syndicating content from another site.

Validating front matter

YAML syntax errors in front matter cause Jekyll build errors. Common mistakes:

Unquoted colons: A colon in a value must be quoted.

# Bad
title: Jekyll: The Complete Guide

# Good
title: "Jekyll: The Complete Guide"

Tab characters: YAML uses spaces, not tabs. Always indent with spaces.

Inconsistent list formatting:

# Bad — mixing inline and block style
tags: [jekyll
  tutorial]

# Good
tags: [jekyll, tutorial]
# Or
tags:
  - jekyll
  - tutorial

Run bundle exec jekyll build --verbose to see detailed error output when front matter parsing fails.

Front matter is the connective tissue of a Jekyll site — it is how content communicates with templates. Mastering it unlocks the full power of Jekyll’s data-driven architecture.