Front Matter Cheatsheet

Use this page when you are writing or editing docs content in the Developer Center and need the exact metadata shape for pages and sections.

For page placement, landing-page cards, module order, and sidebar behavior, see Navigation Map.

For the step-by-step workflow for adding pages, sections, or modules, see Maintenance Workflow.

Front Matter Cheatsheet

These are the front-matter keys currently used in this repo.

Normal Docs Page

---
title: Example Page
description: Explain what this page covers.
icon: i-tabler:book
navigation:
  title: Example
  order: 2
---

Custom Overview Page

---
title: Example Overview
description: Landing-style page for a docs area.
icon: i-tabler:layout-grid
prose: false
prev: false
next: false
aside: false
footer: false
secondarySidebar: false
navigation:
  title: Overview
  order: 1
---

Hidden Internal Page

---
title: Internal Maintainer Page
description: Hidden internal documentation.
navigation: false
layout: docs
---

How title and description Work

The page title displayed in the header comes from the H1 heading in the markdown file, not from the frontmatter title field. A remark plugin (remark-extract-title.mjs) extracts the H1 text and removes it from the body so it renders once via UPageHeader.

• title in frontmatter — used for the sidebar label and SEO. Does not appear as the page heading.
• # H1 in markdown — used as the visible page title in the header.
• description in frontmatter — shown as the gray subtitle under the page title. If omitted, no subtitle is shown.

Add a New Typed Front Matter Field

If you want a front matter field to be part of the project's typed content schema, add it in content.config.ts.

Today, the schema is permissive because it uses .catchall(z.any()). That means extra fields can still work even if they are not explicitly typed yet.

To formalize a new field:

1. Add it to the schema object for the relevant collection.
2. Pick the right Zod type.
3. Keep it optional unless the project really requires it on every page.

Example:

schema: z.object({
  icon: z.string().optional(),
  layout: z.string().optional(),
  description: z.string().optional(),
}).catchall(z.any())

Use this when you want stronger typing, clearer conventions, or better editor support for a field that is already becoming standard in the repo.

Section Metadata With _dir.yml

Use _dir.yml when you need to control metadata for a folder or section instead of a single page.

Keys used here today:

• title
• icon
• navigation.order

Example:

title: Integrations
icon: i-tabler-puzzle
navigation.order: 5

Real examples:

• content/web-client/integrations/_dir.yml
• content/protocol/consensus/_dir.yml
• content/rpc/methods/_dir.yml