# Writing documentation

Author repository MDX, reuse architectural decisions and curate release notes.

## Add a page [#add-a-page]

Create `apps/web/content/docs/section/page.mdx` with `title` and `description` frontmatter. Add its slug to that section’s `meta.json` order. Link to canonical `/docs/...` paths. Use fenced code with a language for build-time highlighting.

```md
---
title: "A useful title"
description: "The decision or task this page explains."
---

## Start with the task

Explain the owner, the change and how to verify it.
```

Supported components include `Callout`, `Steps`/`Step`, `Tabs`/`Tab` (supply a unique `id`), `Cards`/`Card`, `FileTree` and `Diagram`. Tabs use native radio inputs so server-rendered articles remain keyboard-operable without article hydration.

## One source of truth [#one-source-of-truth]

ADRs and the agent connection guide are imported directly from `docs/`, not copied. Relative repository links are rewritten at compile time. Processed Markdown powers the copy button, `.md` routes and agent discovery. English content remains English when navigation changes language.

The collection is synchronous and Vite imports compiled MDX eagerly on the server. Client route data contains rendered public HTML and navigation metadata. The browser does not import the article modules or a Shiki highlighter. Search uses Fumadocs’ server index at `/api/docs/search`.

## Release notes [#release-notes]

Add one dated MDX file under `content/docs/changelog/YYYY-MM-DD-slug.mdx` with title, description and an ISO date string. Describe observable changes and link to their guides and commits. The newest three entries render in full; older entries remain readable individually. The RSS feed is `/docs/changelog/rss.xml`.

```sh
node scripts/changelog-draft.mjs
```

The script prints a draft from merges and Conventional Commits since the latest entry date. A maintainer chooses what belongs in the release, checks dates and edits the prose before saving it. Historical entries are curated groups of changes, not claims of tagged semantic versions.

## Diagrams [#diagrams]

Use the diagram-design workflow, keep its HTML sources and export static SVG. Docs diagrams use the app’s neutral palette and font. Local scrolling preserves readable labels on narrow screens. Update both theme exports and their descriptive text when the underlying flow changes.


## Key files [#key-files]

- [`apps/web/source.config.ts`](https://github.com/CarlosZiegler/doro/blob/main/apps/web/source.config.ts)
- [`apps/web/src/lib/docs/source.ts`](https://github.com/CarlosZiegler/doro/blob/main/apps/web/src/lib/docs/source.ts)
- [`apps/web/src/components/docs/mdx-components.tsx`](https://github.com/CarlosZiegler/doro/blob/main/apps/web/src/components/docs/mdx-components.tsx)