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 panel, copyable code, diagrams, and related-guide cards.

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.

Copy{
  "title": "Homepage",
  "file": "features/homepage.md"
}

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

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.

Copytype 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

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.

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

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:

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

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

Copybun run dev

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