Frontmatter

What is frontmatter#

Frontmatter is a block of YAML at the very top of a markdown file, between two --- lines. It tells moss about the page — its title, date, visibility, and more.

---
title: My First Post
date: 2024-06-15
description: A short summary for search engines and list previews.
---

The rest of the file is your content.

Frontmatter is optional. A file without it still becomes a page — moss uses the filename as the title.

Fixed schema#

Frontmatter uses a fixed schema — moss only recognizes the fields listed on this page. Arbitrary custom fields are silently ignored. If you need custom per-page metadata, store it in body content: a markdown paragraph, a ::: {.meta} fenced div, or a data table.

description: is for SEO meta tags, Open Graph previews, and sitemap summaries. It is not rendered as a visible page deck. For a visible subtitle or lead paragraph, use a > blockquote immediately after the # H1 — the default theme styles h1 + blockquote as a deck.

Identity#

These fields describe what the page is.

title: is the page's title. On article pages moss always renders it as <h1 class="moss-article-title"> above the body — using the filename (title-cased) when title: is absent. If the body itself opens with # Same Title, that body H1 is deduplicated so the reader sees one title, not two.

Body H1s anywhere else are section headers, not document titles. moss does not infer the title from body structure — write the title in title: or rely on the filename.

To suppress the injected title on a specific article (for example, a bespoke landing page), set title: "" (an explicit empty string). This is distinct from omitting the field, which falls back to the filename. Folder and index pages never inject; their bodies render as authored.

Navigation#

These fields control how the page appears in the site's navigation and chrome.

Visibility#

Children#

These fields control how a folder page displays its child pages.

children_source takes a wikilink target, e.g. children_source: "[[news]]".

Card layout uses the cover image from each child's frontmatter.

Set children: false to fully opt out of the auto-emitted child listing on a folder page or the homepage. This suppresses both listing styles — the inline list/summary layout (.moss-article-listing) and the card grid (.moss-collection-grid) — so custom homepages and folder landing pages can lay out their own content without a trailing auto-generated index.

Sort#

sort controls how a folder's children are ordered, which in turn shapes how the cards look.

---
title: Projects
sort: title
---

When sort is absent, moss infers it from the children:

1. Any child has a weight field → sort: weight
2. At least 80% of children have a date field → sort: date
3. Otherwise → sort: title

So most folders need no sort declaration — a blog folder is automatically date, a docs folder with weights is automatically weight, and a folder of dateless projects is automatically title.

Why sort drives appearance: date listings put the date in each card's meta slot; weight and title listings omit the meta slot entirely (no empty space). Folder cards in non-date listings show a small "N articles" subtitle only when they have no description.

The legacy order: [...] field is a back-compat alias for sort: [...].

Media#

See media#Cover images for details.

Layout#

These fields control how the page's content is typeset and sized.

Set these in a folder's cascade to apply them to a whole section:

---
title: Dashboards
cascade:
  content_width: full
---

Cross-listing#

also_in makes an article appear in multiple sections without duplicating the file:

---
title: Building a Trellis
also_in:
  - projects
  - featured
---

series toggles the prev/next navigation chrome at the bottom of each child article. It defaults to on for folders with sort: weight (or an explicit list) — moss assumes authored order implies sequential reading. For sort: date and sort: title it defaults to off. Set it explicitly to override:

# A weighted docs folder, but you don't want prev/next chrome
---
title: Reference
series: false
---

You can also opt a single child out by setting series: false on that article's own frontmatter.

Advanced#

Cascade#

cascade pushes frontmatter values to all descendants, so you don't repeat them on every file:

---
title: Documentation
cascade:
  breadcrumb: true
  comments: false
---

Every page nested under this one inherits these values unless it overrides them in its own frontmatter.