Documentation Writing Content

Front Matter

Front matter is a snippet of YAML or Ruby data which sits at the top of a file between special line delimiters. You can think of front matter as a datastore consisting of one or more key-value pairs (aka a Hash in Ruby). You use front matter to add metadata, like a title or a description, to resources as well as site layouts. Front matter can be used in various ways to set configuration options on a per-file basis, and if you need more dynamic handling of variable data, you can write Ruby code for processing as front matter.

Don’t repeat yourself

If you’d like to avoid repeating your frequently used variables over and over, you can define front matter defaults for them and only override them where necessary (or not at all). This works both for predefined and custom 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 either take the form of valid YAML set between triple-dashed lines, or one of several Ruby-based formats (more on that below). 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 or Ruby-based template code further down in the file, as well as in any layouts or components that the file in question relies on.

Front matter variables are optional

If you want to use template code in a file 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 resource.

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 resource and has a layout defined in the front matter defaults.
  • Using none will produce a file without using a layout file regardless of front matter defaults.

template_engine

You can change the template engine Bridgetown uses to process the file.

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/), 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 start 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>{{ resource.data.food }}</h1>

Ruby templates (ERB, etc.) work the same way:

---
food: Pad Thai
---

<h1><%= resource.data.food %></h1>

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

Predefined Variables #

These resource variables are available out-of-the-box:

Variable Description

date

Specifying a date variable overrides the date from the filename of the resource. 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. You can also use a more human-readable format like this: Wed, 02 Feb 2022 08:55:41 -0800.

category

categories

You can specify one or more categories that the resource 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 resource as a flexible method of building a content folksonomy. As with categories, tags can be specified as a YAML list or a space-separated string.

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.

The Power of Ruby, in Front Matter #

For advanced use cases where you wish to generate dynamic values for front matter variables, you can use Ruby Front Matter (hereafter named rbfm).

Any valid Ruby code is allowed in rbfm as long as it returns a Hash—or an object which respond_to?(:to_h). There are several different ways you can define rbfm at the top of your file. This is so syntax highlighting will work in various different template scenarios.

For Markdown files, you can use backticks or tildes plus the term ruby to take advantage of GFM (GitHub-flavored Markdown) syntax highlighting.

```ruby
{
  layout: :page,
  title: "About"
}
```

I'm a **Markdown** file.

or

~~~ruby
{
  layout: :page,
  title: "About"
}
~~~

I'm a **Markdown** file.

For ERB or Serbea files, you can use ---<% / %>--- or ---{% / %}--- delimeters respectively. (You can substitute ~ instead of - if you prefer.)

For all-Ruby files, you can use ---ruby / --- or ###ruby / ### delimeters.

However you define your rbfm, bear in mind that the front matter code is executed prior to any processing of the template file itself and within a different context. (rbfm will be executed initially within either Bridgetown::Model::RepoOrigin or Bridgetown::Layout.)

Thankfully, there is a solution for when you want a front matter variable resolved within the execution context of a resource (aka Bridgetown::Resource::Base): use a lambda. Any lambda (or proc in general) will be resolved at the time a resource has been fully initialized. A good use case for this would be to define a custom permalink based on other front matter variables. For example:

~~~ruby
{
  layout: :page,
  segments: ["custom", "permalink"],
  title: "About Us",
  permalink: -> { "#{data.segments.join("/")}/#{Bridgetown::Utils.slugify(data.title)}" }
}
~~~

This will now show up for the path: /custom/permalink/about-us

Besides using a simple Hash, you can also use the handy front_matter DSL. Any valid method call made directly in the block will translate to a front matter key. Let’s rewrite the above example:

~~~ruby
front_matter do
  layout :page

  url_segments = ["custom"]
  url_segments << "permalink"
  segments url_segments

  title "About Us"
  permalink -> { "#{data.segments.join("/")}/#{Bridgetown::Utils.slugify(data.title)}" }
end
~~~

This will now show up for the path: /custom/permalink/about-us

As you can see, literally any valid Ruby code has the potential to be transformed into front matter. The sky’s the limit!

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.

Collections