Writing docs
Add a page to this site, use callouts and tabs, and keep it in the sidebar.
Add a page
Pages are MDX files in docs/content/docs. A folder is a sidebar section, and its meta.json sets the title and page order:
{
"title": "How Bones",
"pages": ["get-started", "api"]
}
A folder's index.mdx becomes its Overview link, so leave it out of pages.
A page starts with a title and a one-line description. The description shows under the title and in search.
---
title: Adding a procedure
description: A new endpoint, from router to test to client call.
---
Preview with yarn docs:dev at localhost:3004.
Which section
| Section | Answers |
|---|---|
| Why Bones | What problem does this solve, and how does it compare? |
| What Bones | Why did we pick this tool? |
| How Bones | How do I use it? |
Callouts
:::note[Optional title]
Something worth knowing.
:::
Use note, tip, warning, or danger.
Tabs
Consecutive code blocks with a tab become one tabbed block:
```sh tab="HTTP"
curl http://localhost:3000/health
```
```sh tab="[tRPC](https://trpc.io)"
curl http://localhost:3000/trpc/health.ping
```
Links
- Link to other pages by path:
[Installation](/how-bones/get-started/installation). - Link a tool's name to its home page the first time it appears on a page.
Four passes
Every batch of pages goes through four passes, in order:
- Write. From the code and
NOTES.md, not from memory. A reason for a choice only goes in if someone recorded it. - Tighten. Cut filler. Short declaratives, American English, as
docs/WritingStyleGuide.mddescribes. - Link. The first mention of a tool links to its home page, and every page links to the pages around it.
- Check. Check each claim against the code. Build the site, confirm every link resolves, and run
yarn a11y --only docs.
What to document next is in docs/TODOS.md.
How to write
- Short sentences. Say what it does, not how it will feel.
- Numbers are specific or absent.
- Code, paths, commands, and keys go in backticks.
- If a page needs a scroll bar to explain one idea, split it.
Languages
Pages are written in English only. The site's interface — header, sidebar, search, pager, and footer — is translated, and each page renders under /fr, /es, and /il with its content marked lang="en".
Interface text goes through getT(language, "docs") in server components and useT("docs") in client ones. See Internationalization.
For AI tools
Each page's Markdown is at /raw/<path>.md, and the whole site is at /llms.txt and /llms-full.txt. The Copy as Markdown button on each page reads the first one.