The content sections are markdown-first by design. Writers can focus on clear structure and reusable phrasing while the layout pulls navigation and page metadata from frontmatter.

Frontmatter contract

Every page in src/content/docs/ or src/content/reference/ should declare the same four fields:

---
title: Content Authoring
description: Explain how markdown pages are written and grouped.
section: Writing
order: 1
---

Treat those fields as part of the public content contract for the site.

Writing pattern

The layout already renders the page title and description, so the body can start with context and then move directly into second-level headings.

Recommended structure:

  1. Open with one or two framing paragraphs.
  2. Use ## sections for the main narrative.
  3. Reserve ### for short subtopics only when the page genuinely needs them.

Internal linking

Prefer route links such as Overview or Getting Started so the site remains easy to navigate even as content grows.

Markdown is also a good place to use:

  • tables for comparisons
  • code fences for commands and snippets
  • short ordered lists for repeatable workflows

When React should enter the picture

Keep most content in markdown. Reach for React only when the page needs layout logic, metadata aggregation, or a carefully placed interactive component. That way the publishing experience stays calm instead of turning every content change into a component edit.