Frontmatter

Using Frontmatter in Spinal is a way to make sure all its keys and values, are consistent throughout your Content Type’s content. Opposed to using the flatfile format your static generator provides, where you can add whatever key/value. The UI Spinal gives makes it way easier for your team to edit these values, instead of thinking about the format it needs to (eg. with quotes, as an array, or a hash maybe?).

Supported Frontmatter formats #

Spinal has support for yaml and toml (experimental) formatted Frontmatter. Both are a configuration file format for defining metadata such as title, author, and template for a website or blog.

YAML #

YAML (YAML Ain’t Markup Language) is the most common format used in static site generators. In Spinal data between two --- at the top of the markdown are parsed. For example:

---
title: Frontmatter
description: Frontmatter is what static site generators use to store content's metadata. Spinal gives an easy way to add and edit these.
---

TOML #

TOML (Tom’s Obvious, Minimal Language) is a format supported by some static site generators. It’s straightforward syntax, structure and comment support make it a gain support amongst static site generators (and thus Spinal). Examples:

+++
title = Frontmatter
description = Frontmatter is what static site generators use to store content's metadata. Spinal gives an easy way to add and edit these.
+++

Or like so, notice the different “delimiters”:

---toml
title = Frontmatter
description = Frontmatter is what static site generators use to store content's metadata. Spinal gives an easy way to add and edit these.
---

TOML is currently available as an experimental feature. Reach out to support if you have questions.

Edit Frontmatter settings #

To make changes to your Frontmatter configuration, go to your Content Type’s settings and find the Frontmatter tab. Any Frontmatter found in your Content Type is collected and shown here. In the example below, this Content Type has Frontmatter keys for the default Frontmatter keys Filename, Path and then Title, Description, Section and Order.

Let’s go over each of these settings as there is quite a lot to it.

Key #

Think of it as the identifier of the Frontmatter. It’s the part before the value, eg. section: Content Type. You can only set the key-value when creating a new Frontmatter key.

Type #

The type determines how the field shows up in your editor and how it’s added in the markdown file when published. It can be one of the following:

• string (default type);
• text: shows as a textarea for longer text;
• datetime: shows as a datetime field;
• number: returns a non-string number value;
• boolean: shows as a checkbox to be either true or false;
• checkbox: shows as multiple checkboxes, returns an array;
• select: allows to choose one value;
• upload: allows to drag & drop images to your GitHub repo or Cloudinary account;
• hash: a nested key/value pairing;
• array: a list of value under a nested key.

Instructions #

The Instructions text shows below the field in the editor’s Content settings panel. It can be used to guide your writers on the input needed or why the field is there.

Allowed values #

Allowed values is a comma-separated list of values that works only with the checkbox and select field types. If you imported existing content, the allowed values are collected for you.

Add by default #

Not all Frontmatter needs to be added when you create new content. When Add by default is checked, the Frontmatter is added to the new content. You can always remove it from your your content if not needed after all.

Read only #

You can mark the (default) fields filename and path as read only. When checked, these fields are still shown in the editor’s content settings sidebar, but the value can’t be changed.

Default value #

Both the, default available, filename and folder Frontmatter have the option to set a default value. You could add in a static value, like /posts for the path, but you can also add a magic value that is transformed upon creation, example: posts/%Y-%m-%d-new-content.md. This gets transformed, upon new content creation, as posts/2023-01-01-new-content.md. Assuming today was the first day of 2023. You can use any strftime directives. Works great together with the Read only toggle.

Create new Frontmatter key #

If you need a new Frontmatter key, you can easily create it. Select Add field, and a new set of fields shows. This set is the same as editing Frontmatter, except for the fact you can choose the Frontmatter key.