Any file that contains a YAML front matter block will be processed by Rustyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:

---
layout: post
title: Blogging Like a Hacker
---

Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available for you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.

UTF-8 Character Encoding Warning

If you use UTF-8 encoding, make sure that no BOM header characters exist in your files or very, very bad things will happen to Rustyll. This is especially relevant if you're running Rustyll on Windows.

Front Matter Variables Are Optional

If you want to use Liquid tags and variables but don't need anything in your front matter, just leave it empty! The set of triple-dashed lines with nothing in between will still get Rustyll to process your file. (This is useful for things like CSS and RSS feeds!)

Predefined Global Variables

There are a number of predefined global variables that you can set in the front matter of a page or post.

Variable	Description
layout	If set, this specifies the layout file to use. Use the layout file name without the file extension. Layout files must be placed in the _layouts directory. Using null will produce a file without using a layout file. This is overridden if the file is a post/document and has a layout defined in the front matter defaults. Using none in a post/document will produce a file without using a layout file regardless of front matter defaults. Using none in a page will cause Rustyll to attempt to use a layout named "none".
permalink	If you need your processed blog post URLs to be something other than the site-wide style (default /year/month/day/title.html), then you can set this variable and it will be used as the final URL.
published	Set to false if you don't want a specific post to show up when the site is generated.
parallel	Set to true to enable parallel processing for this page, which can dramatically speed up rendering for complex content with many includes or heavy Liquid processing.
cache	Controls caching behavior for this page. Options include: always, never, or default. Useful for frequently changing pages or pages that need fresh data on each build.
render_priority	Sets the priority level for rendering (1-10, lower numbers = higher priority). High-priority pages are processed first during parallel builds.
memory_limit	Sets a specific memory limit for rendering this page in MB. Useful for very large or complex pages that might exceed default memory allocations.

Render Posts Marked As Unpublished

To preview unpublished pages, run `rustyll serve` or `rustyll build` with the `--unpublished` switch. Rustyll also has a handy drafts feature tailored specifically for blog posts.

Custom Variables

You can also set your own front matter variables you can access in Liquid. For instance, if you set a variable called food, you can use that in your page:

---
food: Pizza
---

<h1>{{ page.food }}</h1>

Predefined Variables for Posts

These are available out-of-the-box to be used in the front matter for a post.

Variable	Description
date	A date here overrides the date from the name of the post. This can be used to ensure correct sorting of posts. A date is specified in the format YYYY-MM-DD HH:MM:SS +/-TTTT; hours, minutes, seconds, and timezone offset are optional.
category categories	Instead of placing posts inside of folders, you can specify one or more categories that the post belongs to. When the site is generated the post will act as though it had been set with these categories normally. Categories (plural key) can be specified as a YAML list or a space-separated string.
tags	Similar to categories, one or multiple tags can be added to a post. Also like categories, tags can be specified as a YAML list or a space-separated string.
render_priority	Rustyll-specific feature that controls the priority of this post in the parallel build system. Posts with higher priority (lower numbers) are rendered first. Values range from 1 (highest) to 10 (lowest). Default is 5.
parallel_deps	Specifies dependencies that must be rendered before this post can be processed. This helps Rustyll optimize the parallel build queue. Format: ["_posts/2023-01-01-post.md"]

Don't repeat yourself

If you don't want to repeat your frequently used front matter variables over and over, define defaults for them and only override them where necessary (or not at all). This works both for predefined and custom variables.

Performance Considerations

Rustyll’s parsing of front matter is significantly faster than Jekyll’s thanks to its Rust implementation. However, for even better performance:

• Consider using front matter defaults in _config.yml instead of repeating the same front matter in many files
• For build-time computations, use the parallel: true setting on complex pages
• Use the cache option strategically for files that rarely change
• Set appropriate render_priority values to ensure important pages are built first
• For very large sites, consider using the parallel_deps option to fine-tune the build order

These optimizations can result in even faster build times, especially for large sites with hundreds or thousands of pages.

Front Matter Formats

Rustyll supports multiple front matter formats for flexibility:

YAML (Default)

---
title: My Page
layout: default
---

TOML

+++
title = "My Page"
layout = "default"
+++

JSON

{{{
  "title": "My Page",
  "layout": "default"
}}}

All formats provide the same functionality, but YAML is the most commonly used.