Created using Perplixity AI

Jekyll Front Matter Guide

Jekyll uses front matter, a block of YAML options placed at the top of your file, to add metadata and configure processing. This guide covers how to format front matter and all common configuration options for Jekyll posts and pages.

What is Front Matter?

Front matter is a YAML block at the very top of your file, surrounded by triple dashes (---). Jekyll reads this block to process the file—assigning templates, defining variables, or specifying metadata.

Example basic front matter:

---
layout: post
title: "Blogging Like a Hacker"
date: 2025-08-26
categories: jekyll guide
tags: [jekyll, blog, static-site]
author: "Jane Doe"
published: true
excerpt: "A quick intro to writing blog posts with Jekyll."
permalink: /blogging/introduction/
---

Anything below the front matter block is normal Markdown, HTML, or Liquid.

Required Syntax

Start with three dashes (---) on a new line.
Add your key-value pairs (YAML).
End with three dashes (---) on a new line.
No blank lines before the first dash!

Common Front Matter Variables

Variable	Applies to	Description
`layout`	post/page	Template file to use from `_layouts` (default, post, page, etc.)
`title`	post/page	Title for the content
`date`	post/page	Publish/sort date. Format: `YYYY-MM-DD HH:mm:ss +/-ZZ:ZZ` (time optional)
`categories`	post/page	List or string; assign categories for grouping/posts
`tags`	post/page	List or string; assign tags for filtering/metadata
`author`	post/page	Author attribution
`published`	post/page	`true`/`false`; mark as published/unpublished
`excerpt`	post/page	Short summary for lists/previews
`permalink`	post/page	Custom URL for the file/page
`description`	post/page	SEO, meta, preview, or context description
`redirect_to`	page	List or string; URLs to redirect this page to
`hidden`	page	Prevent from showing in navigation (used in some themes)
`lang`	page	Language code (e.g., `en`, for translation/localization support)
`toc`	page	Enable/disable automatic table of contents
`showMiniToc`	page	Enable/disable Github Docs-style mini TOC (`true`/`false`)
`draft`	post	Mark as draft (not published until manually published)
`sitemap`	post/page	Exclude from sitemap.xml (`false`)

Examples

Using Categories and Tags

---
categories:
  - guides
  - markdown
tags:
  - tips
  - beginners
---

You may also use space-separated strings:

---
categories: guides markdown
tags: tips beginners
---

Multiline Variables

For long descriptions or excerpts, you can use YAML’s multiline format.

Folded style (line breaks become spaces):

---
description: >
  This page demonstrates advanced usage of Jekyll front matter.
  You can have multiple lines here.
---

Literal style (preserves newlines):

---
excerpt: |-
  This is a paragraph
  with multiple lines
  exactly as written.
---

Custom Variables

You can create any key-value you want:

---
layout: page
title: Custom Page
custom_variable: "Display this value using "
---

Special Page Types

Posts (in _posts): Jekyll automatically adds a date and slug based on filename.
Pages (anywhere): Use layout: page or custom layouts, add custom front matter as needed.

Optional: Empty Front Matter

To enable Liquid templating on a plain page, use empty front matter:

---
---

Best Practices & Tips

Always start files with front matter in triple dashes.
Use lists for categories and tags for clarity.
Prefer ISO 8601 date formats for international compatibility.
Avoid unsupported YAML features (anchors, advanced references).
Escape single quotes using two single quotes or switch to double quotes for safety.
Preview your site: Jekyll reporting will indicate front matter errors.
Use custom variables to pass data globally to layouts, includes, or navigation.

Resources

You’re now ready to format front matter for any Jekyll post, page, or collection!