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:

---
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:

---
type: doc
---

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

---
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.

---
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.

# Page title

## Section

### Detail

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

Use root-relative internal links:

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:

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

Use twoslash for TypeScript examples that benefit from type inspection:

const 
const count: 1count = 1;

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

Live previews

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

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

Components in MDX

Import components at the top of the file:

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.