Authoring

How to write pages — frontmatter, sections, alerts, code blocks.

Adding a page#

Drop a .md or .mdx file in src/content/docs/. The route mirrors the path:

File	URL
`src/content/docs/index.mdx`	`/`
`src/content/docs/getting-started.md`	`/getting-started/`
`src/content/docs/guides/authoring.md`	`/guides/authoring/`

Frontmatter#

---
title: Page title
description: Optional summary, shown under the title and in <meta description>.
sidebar:
  label: Optional sidebar label
  order: 10
  hidden: false
---

Only title is required. See the frontmatter reference for all fields.

Sections#

Section grouping is by directory:

Path	Sidebar group
`src/content/docs/*.md`	Start here
`src/content/docs/guides/*`	Guides
`src/content/docs/reference/*`	Reference
`src/content/docs/contributing/*`	Contributing

To add or rename groups, edit the SECTIONS array in src/lib/nav.ts.

Ordering#

Pages are sorted by sidebar.order ascending, then alphabetically. Use sparse numbers (10, 20, 30) so you can insert later without renumbering.

Alerts#

GitHub-style blockquote alerts work via remark-github-blockquote-alert:

> [!NOTE]
> Useful information.

> [!TIP]
> Helpful suggestion.

> [!IMPORTANT]
> Crucial info.

> [!WARNING]
> Be careful.

> [!CAUTION]
> Danger zone.

Renders as:

NOTE

Useful information.

WARNING

Be careful.

Code blocks#

Fenced code blocks use Shiki with github-light and github-dark-dimmed themes. A copy button appears on hover automatically.

```ts
const x: number = 42;
```

Headings + TOC#

## and ### headings get auto-generated anchor links and appear in the right-rail TOC with scroll-spy.

Images#

Drop them in public/ and reference with absolute paths:

![alt](/diagrams/architecture.svg)

MDX#

Rename the file to .mdx to use components in markdown. Import them at the top:

---
title: My page
---

import Counter from '@/components/Counter';

<Counter client:load />