---
title: Writing
description: Write concise MDX docs with frontmatter, headings, links, code samples, previews, and components.
order: 6
tags: [mdx, writing]
---

# Writing

Imprensa pages are MDX: Markdown for prose, JSX for components, and frontmatter for metadata. Write for humans first; Imprensa uses the same content for navigation, search, sitemap metadata, and AI exports.

## Page metadata

Start each page with frontmatter:

```mdx
---
title: Configuration
description: Configure the imprensa Vite plugin.
order: 2
tags: [config, plugin]
---
```

Use:

- `title` for navigation, search, and metadata
- `description` for previews and AI summaries
- `order` for sidebar sorting
- `tags` for search context
- `type` to choose how Imprensa treats the file: `doc` (default), `custom`, or `link`
- `draft: true` for unpublished work

## Page types

Most pages use the default type:

```mdx
---
type: doc
---
```

Use `custom` when the MDX file renders its own layout and should not receive Imprensa prose classes, doc toolbar, or pager:

```mdx
---
title: Showcase
type: custom
---

<div class="grid gap-4 md:grid-cols-3">...</div>
```

Use `link` for sidebar items that point somewhere else. Link pages are shown in navigation but are not rendered or prerendered as docs pages.

```mdx
---
title: GitHub
type: link
link: https://github.com/ilhajs/imprensa
external: true
---
```

Set `external: true` to open the link in a new tab.

## Headings

Every page should have exactly one `h1`. It does not need to match the frontmatter `title`: use `title` for navigation/search labels and the `h1` for the best visible page heading. Do not skip heading levels.

```mdx
# Page title

## Section

### Detail
```

Keep headings specific; they become anchor targets and improve search quality.

## Links

Use root-relative internal links:

```mdx
See [Configuration](/guide/configuration).
```

By default, builds fail on dead internal links and missing anchor targets. That is intentional: fix broken links before publishing.

## Code blocks

Fence code with the correct language for highlighting:

````mdx
```ts
const greet = (name: string) => `Hello, ${name}`;
```
````

Use `twoslash` for TypeScript examples that benefit from type inspection:

```ts twoslash
const count = 1;
//    ^?
```

Configure loaded languages and themes in `vite.config.ts`.

## Live previews

Add `preview` to render an interactive example below a code block:

```tsx preview
import ilha from "ilha";

export default ilha
  .state("count", 0)
  .on("[data-action=inc]@click", ({ state }) => state.count(state.count() + 1))
  .render(({ state }) => (
    <button data-action="inc" class="rounded bg-blue-600 px-3 py-2 text-white">
      Count: {state.count()}
    </button>
  ));
```

Keep previews small. They should demonstrate one idea, not become a second application.

## Components in MDX

Import components at the top of the file:

```mdx
import { Badge, Button } from "areia";

<Badge>New</Badge>
<Button>Action</Button>
```

Use components when they clarify the documentation. Prefer Markdown for ordinary prose.

## Good docs style

- Lead with the practical answer.
- Keep examples copy-pasteable.
- Explain defaults before edge cases.
- Link to related pages instead of repeating long sections.
- Remove placeholder content before publishing.