# Writing documentation

Write documentation in ordinary Markdown under `docs/src/`. The standalone docs app turns those pages into the same reading interface used by set-me-up-docs: searchable guides, a hierarchical contents



Write documentation in ordinary Markdown under `docs/src/`. The standalone docs
app turns those pages into the same reading interface used by set-me-up-docs:
searchable guides, a hierarchical contents panel, copyable code, diagrams, and
related-guide cards.

## Choose a location [#choose-a-location]

Use the visitor section for explanations of controls and reading workflows. Put
setup commands in Getting Started, system responsibilities in Architecture,
feature implementation details in Features, and contracts in API Reference.
Contributing covers checks, conventions, and release expectations.

Add the page to `docs/navigation.json` so it appears in the sidebar and search.
The validator rejects a Markdown guide that has not been registered there.
A navigation entry provides the concise sidebar label; the page's H1 provides
the full article title. Sidebar rows expand to fit wrapped labels with padding
on every side; keep labels concise, and check a two-line label when reviewing
navigation changes.

```json title="Navigation entry"
{
  "title": "Homepage",
  "file": "features/homepage.md"
}
```

## Write for a specific task [#write-for-a-specific-task]

Start with what the reader can accomplish. Explain the expected result before
listing implementation details. Show the command and the directory where it runs,
then explain any prerequisite or optional service that changes its behavior.

Use sections to separate decisions and workflows rather than splitting every
sentence into a heading. Start with a single H1, use H2 for main sections, and H3
for steps or subtopics. The generated page template supplies the visible H1;
the content converter removes the duplicate from the body.

## Syntax-highlighted examples [#syntax-highlighted-examples]

Specify a language on every fenced code block. Use `bash` or `sh` for shell
commands, `ts` or `tsx` for application code, `json` for configuration, and `yaml`
for frontmatter. Use `text` when the content has no meaningful language.

Shiki applies language-aware token colors in both themes. The code UI preserves
monospace text, horizontal scrolling, and a copy control. A `title` in the fence's
metadata adds a visible filename or label. Give the reader a path when they need
to know which file owns the example, and avoid putting a filename where a language
identifier belongs.

```ts title="Example: a typed layout preference"
type HomeLayout = "hero" | "split";

const defaultLayout: HomeLayout = "split";

function isHomeLayout(value: string): value is HomeLayout {
  return value === "hero" || value === "split";
}
```

Keep examples focused enough to read without scrolling through an entire module.
Use placeholders for local paths and credentials. Explain a command's effect
instead of assuming that syntax coloring makes it self-explanatory.

## Diagrams [#diagrams]

Use a fenced `mermaid` block when a relationship or sequence is clearer visually.
Flowcharts work well for navigation, data ownership, and routing. Sequence diagrams
work well for request processing or a visitor interaction. Keep labels concise and
place the explanatory prose alongside the figure.

```mermaid
"flowchart LR\n    Markdown[Write Markdown] --> Navigation[Register the guide]\n    Navigation --> Generate[Generate MDX]\n    Generate --> Preview[Review the rendered page]\n    Preview --> Validate[Run documentation checks]"
```

Diagrams follow the selected light or dark theme and can scroll on narrow screens.
Their Markdown export preserves the Mermaid source. If a rendering failure occurs,
the source remains available rather than silently disappearing from the guide.

## Cards with icons [#cards-with-icons]

Use guide cards for a small set of related destinations or a choice of reading
paths. Keep actual steps and reference lists as normal Markdown lists. Cards are
most useful when their descriptions help someone choose the next page.

A cards block contains ordinary Markdown links and a short description after an
em dash:

```markdown title="Related-guide cards"
:::cards

- [Installation](/docs/getting-started/installation) — Start the site locally.
- [Architecture](/docs/architecture/overview) — Understand the major components.

:::
```

The converter renders those entries with the reference app's `GuideCards`
component. Icons identify the destination's subject: setup, architecture, features,
reference, or a general guide. The entire card is a keyboard-focusable link, and
hover and focus states remain visible in either theme. Exported Markdown expands
the cards back into a readable linked list.

## Preview and validate [#preview-and-validate]

From the repository root, start the portfolio and docs service in separate
terminals. Inside the Flox environment, use:

```bash title="Portfolio terminal"
bun run dev
```

```bash title="Documentation terminal"
bun run docs:dev
```

Open `http://localhost:3000/docs`. After editing source Markdown, run
`bun run --cwd docs generate:content` and review the resulting page. Check heading
nesting, code titles and copy behavior, diagrams, guide-card destinations, and a
narrow mobile viewport.

Run `bun run docs:check` before finishing. The full repository check also includes
docs validation. Changes to the source interface should retain its provenance;
content and branding adaptations belong in the documented adapter files.

- [Documentation architecture](/docs/architecture/documentation): Content generation, retained reference source, and Vercel routing.
- [Quality and releases](/docs/contributing/quality-and-releases): The checks and release sequence used by this repository.