Front Matter

Front matter is a snippet of YAML which sits between two triple-dashed lines at the top of a file. You use front matter to add metadata, like a title or a description, to files such as pages and posts as well as site layouts. Front matter can be used in various ways to set configuration options on a per-file basis, and starting with Bridgetown v0.13, you can even write Ruby code for dynamic front matter variables.

Table of Contents

Using Front Matter

Any file that contains a front matter block will be specially processed by Bridgetown. Files without front matter are considered static files and are copied verbatim from the source folder to destination during the build process.

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 add custom variables of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or components that the file in question relies on.

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 Bridgetown to process your file. (This is useful for things like 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 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 Bridgetown to attempt to use a layout named "none".

permalink

If you need your URLs to be something other than what is configured by default, (for posts, the default is /category/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 page to show up when the site is generated.

Render pages marked as unpublished

To preview unpublished pages, run bridgetown serve or bridgetown build with the --unpublished switch.

Custom Variables

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

---
food: Pizza
---

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

You can also use a document’s front matter variables in other places like layouts, and you can even reference those variables in loops through documents or as part of more complex queries (see Liquid filters for more information).

Predefined Variables for Posts

For documents in the posts collection, these variables are available out-of-the-box:

Variable Description

date

Specifying a date variable overrides the date from the filename 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

You can specify one or more categories that the post belongs to, and then you can use that to filter posts in various ways or use the "slugified" version of the category name to adjust the permalink for a post. 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 as a flexible method of building a lightweight content taxonomy. As with categories, tags can be specified as a YAML list or a space-separated string.

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.

Advanced Front Matter Data Structures

YAML allows for pretty sophisticated methods of structuring data, for example representing arrays or hashes (key/value pairs). You can also write out longer multi-line strings like so:

---
description: |
  I am a multiple line
  string value that can
  go on and on.
---

For reference, here’s a side-by-side comparison of YAML data structures and their equivalents in Ruby.

UTF-8 Character Encoding Warning

If you use UTF-8 encoding, make sure that no BOM header characters exist in your files or you may encounter build errors.

Ruby Front Matter

For advanced use cases where you wish to generate dynamic values for front matter variables, you can use Ruby Front Matter (new in Bridgetown v0.13). This feature is available for pages, posts, and other documents–as well as layouts for site-wide access to your Ruby return values.

This requires the environment variable BRIDGETOWN_RUBY_IN_FRONT_MATTER to be set to "true" in your development and deployment setups. Otherwise the code will not be executed and will be treated as a raw string.

Here’s a blog post with a high-level overview of what Ruby Front Matter is capable of and why you might want to use it.

To write Ruby code in your front matter, use the special tagged string !ruby/string:Rb. Here is an example:

---
title: I'm a page
permalink: /ruby-demo
calculation: !ruby/string:Rb |
  [2 * 4, 5 + 2].min
---

Title: {{ page.title }}
Calc Result: {{ page.calculation }}

In the final page output rendered by Liquid, the value of the calculation variable will be the return value of the Ruby code.

You can write any Ruby code into a front matter variable. However, if you need to write a lengthy block of code, or write code that is easily customizable or reusable in multiple contexts, we still recommended you write a Bridgetown plugin—either in the plugins folder in your site repo or as a separate Gem-based plugin.

Depending on if your Ruby code is added to a document or a layout, certain Ruby objects are provided for your use.

For layouts, you can access: site, layout, and data.

For documents, you can access: site, page or document (they are equivalent), renderer, and data.

Documentation on the internal Ruby API for Bridgetown is forthcoming, but meanwhile the easiest way to debug the code you write is to run bridgetown console and interact with the API there, then copy working code into your Ruby Front Matter.

For security reasons, please do not allow untrusted content into your repository to be executed in an unsafe environment (aka outside of a Docker container or similar). Just like with custom plugins, a malicious content contributor could potentially introduce harmful code into your site and thus any computer system used to build that site. Enable Ruby Front Matter only if you feel confident in your ability to control and monitor all on-going updates to repository files and data.

Next: Collections