Frontmatter Preview

Automatically display custom frontmatter fields as a metadata table beneath the page title.

The frontmatter preview block appears automatically below the page title whenever a document contains non-ignored frontmatter keys. It renders those custom fields as a compact key/value table — useful for surfacing document metadata such as authorship, status, or version without embedding it inline in the prose.

This very page demonstrates the feature: the author and status fields you see rendered above were declared in its own frontmatter.

When the Block Appears

The block appears only when at least one frontmatter key survives filtering. Framework-managed keys (title, description, sidebar_position, tags, etc.) are stripped by default. If every key is on the ignore list, nothing is rendered.

Set frontmatterPreview: false in src/config/settings.ts to disable the feature entirely for all pages.

Default Ignore List

The following keys are ignored by default. They correspond to every field defined in the content schema and would be redundant to show again:

Any key not in this list will be shown automatically.

Customizing the Ignore List

The frontmatterPreview setting in src/config/settings.ts accepts two mutually exclusive knobs.

extraIgnoreKeys — extend the defaults

Add keys to the ignore list without discarding the defaults. Use this when you have a project-wide custom frontmatter field that should remain hidden everywhere:

frontmatterPreview: {
  extraIgnoreKeys: ["reviewed_by", "internal_id"],
},

ignoreKeys — replace the defaults

Completely replaces the built-in ignore list. Use this when you want full control over which keys are hidden. When ignoreKeys is present, extraIgnoreKeys is ignored.

frontmatterPreview: {
  ignoreKeys: ["title", "description", "sidebar_position"],
},

Disable the Feature

Set frontmatterPreview: false to remove the block from all pages at once:

frontmatterPreview: false,

Example

The following frontmatter produces a preview table with author and status visible, while title, description, and sidebar_position are filtered out:

---
title: My Release Notes
description: What changed in v2.
sidebar_position: 5
author: Jane Doe
status: released
---

The rendered table shows:

For the full configuration reference, see Configuration — frontmatterPreview.

Custom Renderers

By default, frontmatter values render as plain text. To replace a value with a styled component — a colored pill, a link, an icon — register a custom renderer in src/config/frontmatter-preview-renderers.tsx.

Component contract

Each renderer is a Preact component that receives FrontmatterRendererProps:

Registering a renderer

Open src/config/frontmatter-preview-renderers.tsx and add a key to the exported frontmatterRenderers map. Each value is a component function that receives FrontmatterRendererProps and returns JSX or null:

discount: ({ value }) => {
  if (value !== true) return null;
  return (
    <span className="inline-block px-hsp-sm py-vsp-2xs text-caption rounded-full bg-danger text-fg">
      ON SALE
    </span>
  );
},

This page’s own frontmatter includes discount: true, status: "stable", and difficulty: "beginner" — the metadata table at the top of this page shows them rendered as colored pills.

Ignore-list precedence

A renderer registered for an ignored key has no effect. The ignore list is applied before renderer lookup — if a key is suppressed, the row is never rendered and the renderer is never called.

To surface a framework-managed key (such as draft) with a custom renderer, first remove it from the ignore list in src/config/settings.ts:

frontmatterPreview: {
  // Must explicitly list all keys to keep hidden — ignoreKeys replaces the defaults
  ignoreKeys: ["title", "description", "sidebar_position", "tags"],
},

Register your renderers in src/config/frontmatter-preview-renderers.tsx in your project. The empty map ships by default.