---
title: Writing docs
section: Project
order: 1
description: Write Markdown pages with shared components, code examples and stable heading links.
---

# Writing docs

Write documentation in `content/docs/` and posts in `content/blog/`.
Pages share the same Markdown pipeline and components. No per-file imports are needed.

## Frontmatter

Docs require `title`, `section` and numeric `order`; `description` is optional.
Blog posts require `title`, `description`, quoted `date` (`YYYY-MM-DD`), `author`,
`tags` (a list), and boolean `draft`. `image` is optional. The author is a key in
`content/blog/authors.json`. Drafts appear in development and are omitted from production.

## Callouts

<Callout type="note">

Keep related explanations close to the example they describe.

</Callout>

<Callout type="tip" title="A helpful shortcut">

Code fences accept a language and an optional `title="filename"`.

</Callout>

<Callout type="warning">

Never include credentials in Markdown files or code examples.

</Callout>

<Callout type="danger">

Check destructive commands before publishing them.

</Callout>

## Tabs

Wrap named `<Tab title="…">` panels in `<Tabs label="…">`.
Use Left/Right arrows, Home and End to select a tab. Every panel remains readable without JavaScript.

<Tabs label="Installation platform">
<Tab title="macOS">

Install the macOS package with your preferred package manager.

</Tab>
<Tab title="Linux">

Install the Linux package for your distribution.

</Tab>
<Tab title="Windows">

Install the Windows package and open a terminal.

</Tab>
</Tabs>

## Code groups

Use `<CodeGroup>` with `<Tab title="…">` children to compare code samples.
All code fences have copy buttons; unknown languages render as plain text.

<CodeGroup label="Client examples">
<Tab title="TypeScript">

```ts title="app.ts"
const response = await fetch('/api/status');
console.log(await response.json());
```

</Tab>
<Tab title="Python">

```python title="app.py"
import urllib.request
print(urllib.request.urlopen('/api/status').status)
```

</Tab>
</CodeGroup>

## Steps

Use level-three headings inside `<Steps>` to number a sequence. Keep blank lines around Markdown inside components.

<Steps>

### Create a file

Add a Markdown file in the appropriate content folder and fill in its frontmatter.

### Preview the page

Run `npm run dev` and check the content in light and dark mode.

### Publish

For posts, set `draft: false`. Run `npm run build` to validate all content.

</Steps>

## Heading links

Headings generate stable IDs. Level-two through level-four headings include a permalink.
Repeated headings receive numbered suffixes; formatting is preserved in the text and removed from the ID.
