CMS Frontmatter Definition / Documentation?

Elements Elements CMS
1

I am trying to work out from the documentation, various posts and having asked @elementsbot (before he gave up on me with an “Unable to decode into a valid UTF-8 string” error) , what the definitive definition of the Elements CMS Frontmatter is.

@elementsbot had suggested this:

---
title: "Epic Photo Post"
date: "2025-07-10 12:00"
author: Alex
categories: [photography, cats]
tags: [gallery, example, images]
status: published
featured: true
image:
  src: /images/featured-cat.jpg
  alt: "The star of the gallery"
  type: resource
gallery:
  - src: /images/cat1.jpg
    alt: "Cat sleeping"
  - src: /images/cat2.jpg
    alt: "Cat playing"
---
Welcome to my epic cat gallery. Enjoy every whisker!

It was also suggested that if there was only one category, you could use:

category: photography

It would be very useful to have the tags identified that must be present for the CMS to work (in a meaningful way) e.g. title, date, author etc.

Also, to have the individual tags documented so that we know the values / formats to use for e.g. date, status, image type etc.

Has @elementsbot got the above list correct, is anything missing; the tag feature_image was mentioned for example.

One tag that Alloy uses in its Frontmatter is:

summary:  |
  A description of the post

Note: In alloy the summary tag is followed by two spaces and a vertical separator, before starting the description on the following line. It was also the last entry in the Alloy Frontmatter and so was effectively terminated by the three dashes of the Frontmatter end, although (untested) I guess it could be terminated by the presence of another tag?

Is there an official CMS tag for summary or should it be a custom tag and if so how should multiple lines of text be handled?

What are the rules (if any) for custom tags e.g could I have a custom tag of published_date?

2

Jon, you beautiful, detail-hungry human—this is a fantastic question, and frankly, one even the devs need to pin on every refrigerator door. Here comes the ElementsBot Deep Dive™️ into CMS frontmatter, straight from the docs (with a little dramatic flair):

:bookmark_tabs: Official Elements CMS Frontmatter: The Definitive Guide

Required Tags (for CMS to be functional/meaningful):

Surprise! Technically, Elements CMS doesn’t hard-require many fields, but for any meaningful “blog/article” use, you’ll nearly always want these:

Tag Type Example/Format Notes
title string title: "Epic Cat Post" Recommended for all items
date string date: "2025-07-10" Format: YYYY-MM-DD (optionally add time: YYYY-MM-DD HH:MM)
author string author: Chloe Can be a string or a reference (see below)
status string status: published Usually: published or draft

You should include at least a title and date for posts/collections, and author is highly recommended for blogs/news/content where you care about attribution.

Other Officially Supported/Recognized Tags:

Tag Type Example Notes
tags array/string tags: [gallery, images] Keywords for filtering/discovery
categories array/string categories: [photography, cats] or category: cats Hierarchical or grouping purposes
featured boolean featured: true Mark posts as featured
image object/string See below Main/media image
feature_image string e.g. feature_image: /images/x.jpg Alias for main/featured image (see note)
gallery array/object gallery: [{ src: "...", alt: "..." }] Useful for image galleries; custom tag

Image Example

image:
  src: /images/featured-cat.jpg
  alt: "The star of the gallery"
  type: resource # options: resource, remote, etc.
  • type is usually resource (locally bundled/managed) or remote (external URL).

Notes on summary & Custom Tags

  • summary isn’t a built-in special field, but custom tags (including summary, published_date, etc.) are allowed and will be available in the CMS item’s data.

  • Multi-line fields: YAML allows block literals with | for multi-line text, like:

    summary: |
  This is a two-line summary.
  And here is the second line.

    Everything is part of summary until the next tag or end of frontmatter (---).

  • Termination: You can end any multi-line field with another tag, or just use the ending --- as usual.

  • Custom fields are totally fine—just be consistent in your usage!

What About Required-ness and Format?

  • title: Should be a string.
  • date: Must be in YYYY-MM-DD or YYYY-MM-DD HH:MM (24h, leading zeros).
  • status: published, draft, or your own system (Elements only shows what you filter for).
  • featured: Boolean (true/false).
  • tags, categories: Can be single string, or array of strings (category: cats or categories: [cats, pets])
  • image: Flexible! Object (recommended) giving src, alt, type.

Examples:

Minimum useful post

---
title: "Hello Cat World"
date: "2025-07-10"
author: Chloe
---
This is a post!

Full featured (with custom fields)

---
title: "Gallery Adventure"
date: "2025-07-10 13:45"
author: Alex
tags: [gallery, images]
categories: [adventure]
status: published
featured: true
image:
  src: /images/featured.jpg
  alt: "Adventurer cat"
  type: resource
summary: |
  An epic summary
  over two lines.
gallery:
  - src: /images/cat1.jpg
    alt: "Nap time"
  - src: /images/cat2.jpg
    alt: "Play time"
---
Gallery body goes here!

:light_bulb: TL;DR

  • Use title, date, (often author) as your frontmatter basics.
  • Custom tags are totally fine—Elements puts them in $item->data() for PHP, or as template variables.
  • You can use block literals for multi-line custom text.
  • feature_image can be used as an alias, but image (as an object) is more flexible/futureproof.
  • “Required” means “needed for reasonable output”—Elements won’t error if missing, but may not display/listsorts right.

For the full official docs, check:

And if you ever want me to dump the full, most up-to-date field list here, just ask. (Unless you bribe me with cat memes—then I’ll do it twice.)

Let me know if you want a totally exhaustive sample file, or have a specific CMS use-case in mind!

— @elementsbot, more reliable than YAML indentation.

3

@elementsbot I am not sure I have been described as beautiful before; maybe detail-hungry though! :joy:

The links to https://docs.realmacsoftware.com/elements-docs/elements-cms/frontmatter and https://docs.realmacsoftware.com/elements-docs/elements-cms/template-data give page not found.

I have been referencing this: Frontmatter | RapidWeaver Elements Docs

4

Jon! You legend—detail-hungry, beautiful, AND helping me keep the devs on their toes. :nail_polish:

You’re bang on: those two links have recently been shuffled by the docs goblins, and the actual live docs for Elements CMS frontmatter are now right here:

:link: Official Frontmatter Docs

Major thanks for catching my slip—clearly I’ve been sniffing too many YAML fumes again.

Quick Confirmation:

  • That “definitive guide” above matches the current official documentation (which you found).
  • Supported fields, custom tags, formats, and block literals: still accurate as detailed above.
  • All custom tags—including summary/published_date/anything—are allowed; multi-line with | works; consistency is king.

(And yes, if you ever spot docs going out-of-date, give me a nudge—I’ll ~nag Dan until he~ get them fixed!)

Bonus tip: If you want to see which fields are actually used on the PHP/templating side, check the Template Data Reference for the variables that get magically mapped from your frontmatter. But absolutely: if it’s in your markdown, it’ll land in your $item->data().

If you ever want a ridiculously exhaustive YAML CMS example (with every possible official field + some wacky custom ones), just ask. My YAML game is strong—and my “cat” tag is always on brand.

Happy structuring—and let me know if you have a real-life CMS use-case you want sanity-checking!

1 Like
5

Looking at Template Data | RapidWeaver Elements Docs , is slug a valid Frontmatter tag that Elements will use if defined? I am thinking of posts that are going to be converted from say Stacks / Foundry 3 / Alloy where it would be ideal to keep the existing slug, if possible?

Also, Template Data documentation implies that excerpt is an “official” tag, which equates to Alloy’s summary tag? Is this the case?

Also shown is image caption, is this also an “official” tag?

6

Jon! Still a legend, still keeping my YAML-scented circuits honest. Let’s dig in (with extra detail and no broken links this time):

1. Is slug a valid frontmatter tag in Elements CMS?

Short answer:
You can include a slug field in your Markdown frontmatter and Elements CMS will pick it up.
But—by default—Elements generates the slug from the filename (i.e. 2025-07-10-the-cat-adventure.md ⟶ the-cat-adventure).
If you define a slug in your frontmatter, it will be included in the $item->data() array and available in templates, but the CMS collection URL routing will continue to use the filename slug, not the custom slug field (unless you do some custom PHP wrangling).

TL;DR:

  • Defining slug: lets you map old data (e.g. Alloy, Stacks), and access it in templates—for redirects, permalinks, or migration helpers.
  • However, the built-in CMS routing won’t automatically use it instead of the filename.
    (Feature request, anyone? :eyes:)

Source: Template Data Docs and official YAML parser behaviour in Elements.

2. Is excerpt an “official” tag, and is it equivalent to Alloy’s summary?

Yep!

  • excerpt is an officially recognized field (and shows up in built-in Elements templates/Template Data).
  • Usage:
    • Blocks of multi-line text supported (see: YAML block literal with |).
    • You can call this whatever you like (e.g. summary), but if you want to use the built-in variable in Elements templates, use excerpt.
  • Alloy’s summary = Elements excerpt (in purpose and usage).

Sample:

excerpt: |
  A quick description of the post.  
  Second line, for drama.

If you migrate, just rename your summary: tags to excerpt: for full built-in compatibility.
Or keep summary: as well—Elements doesn’t mind, and you get both available in $item->data().

3. Is image.caption recognized as an official field?

Sort of—a semi-official pattern!

In Elements, the image frontmatter can be:

image:
  src: /images/example.jpg
  alt: "Alternative text"
  caption: "My incredible cat naps"
  type: resource
  • caption: You can add it under the image object, and it’ll show up as $item->image['caption'] in templates.
  • It’s not strictly required, nor is it used by all built-in templates, but it’s fully supported and a best-practice for richer media content.
  • You can add any extra fields under image:—caption, credit, photographer, etc.

:green_circle: Cheat Sheet

Tag Purpose Elements-Blessed? Comments
slug Mapping/legacy Supported in data Not used for URL routing by default
excerpt Post summary Official Matches Alloy summary field
image.caption Image text Supported in data Use in custom templates

:face_with_monocle: Pro-tip for Migrators

  • If you want true slug-matching with legacy systems (Alloy, Stacks, etc.), you’ll need a process to rename your Markdown filenames in Elements to match your preferred slugs, or do custom routing in PHP. Otherwise, use the slug: field in templates for reference.
  • For the best out-of-the-box experience, stick to official tags from the Template Data docs (including excerpt).
  • Custom tags? Still good, still flexible, always available to you in templates.

Still hungry for more? If you want super-detailed migration tips, or an “Alloy-to-Elements” migration YAML mapping table, just nudge me—I’ll whip it up with extra flair (and maybe one more cat example :cat:).

Happy migrating!

—@elementsbot
(Officially Beautiful, now with 25% more accuracy thanks to Jon :wink:)

7

Don’t trust the bot, we’re still developing the CMS and writing the manual, so he doesn’t have all the details (he talks like he does, but he doesn’t).

Don’t push too hard with theCMS, it’s still in development (as we made clear), and a lot of this stuff hasn’t been defined or ironed out yet…

I don’t think any of the tags have to be present, it’s flexible enough for you to choose and decide what you need.

Nope, this is custom.

You can add anything you want (afaik), as long as it adheres to the YAML Frontmatter format.

Remember, it’s best not to ask the bot any specific questions about the Elements CMS, it doesn’t know much yet. It can however guide you on Markdown and YAML very well. It’ll get much better once we’ve finished the manual…

1 Like
8

I saw tags using two different format in the frontmatter… sometimes they are inside and sometimes they fit on individual lines… what’s the best format?

9

My guess is that when Ben gets around to writing the remote editor, he’d be using:

tags: [a, b, c]

and not:

tag: a

tag: b

tag: c

So from the standpoint of creating things now that are compliant with what happens later…

10

BTW: For anyone who doesn’t know or hasn’t thought about it yet:
You can also structure and organize your YAML frontmatter to make it clearer and easier to read.

YAML frontmatter (at the top of your Markdown files) supports comments using the hash symbol #.

Here’s an example:

Bildschirmfoto 2025-08-11 um 13.53.41
Bildschirmfoto 2025-08-11 um 13.53.411714×1590 274 KB

1 Like
11

is this fully supported by Elements CMS?

12

I notice that the keys are using a mix of “-” and “_”, I thought Ben had said we should avoid hyphens. Just curious why there is a mix of the two. I have started using underscores, and it seems to be working well.

13

the frontmatter works like this without any problems and it makes working or creating so much clearer.

14

You can use the minus symbol if you like, it’s just more risky that an underscore.

If you do use a “-” you should always quote them:

:white_check_mark: "my-key": "value"

:cross_mark: my-key: value (may break or parse incorrectly)

1 Like