Docs
Docs that live in the repo, change with the code, and ship as static HTML that people and AI tools can both read.
The problem
Docs drift. They live in a wiki or a hosted platform, away from the code, so a pull request changes how something works and nothing reminds anyone to update the page.
What Bones does
The docs — this site — are MDX files in the repo, in docs/content/docs.
- They change with the code. A page is edited in the same pull request as the code it describes, and reviewed with it.
- Three sections. Why Bones covers each feature and the problem it solves. What Bones covers each tool and why it was picked. How Bones covers using them.
- Static HTML. The site is a Next.js static export. Every page is a real HTML file, crawlable without JavaScript.
- Search with no service. The search index is built with the site, and the reader's browser runs every query. ⌘K or Ctrl+K opens it.
- Readable by AI tools. Every page's Markdown is at
/raw/<path>.md, and the whole site is at/llms.txtand/llms-full.txt. Each page has a Copy as Markdown button. - On brand. Every component is Bones, built on the same tokens as the apps, in light and dark.
- Four languages around English pages. The header, sidebar, search, and footer are translated into French, Spanish, and Hebrew. The pages themselves stay in English. See Internationalization.
- Checked like the rest. Every pull request that touches the docs builds them, sweeps them for accessibility, and checks each page's CSP.
Every batch of pages goes through four passes: write, tighten, link, and check each claim against the code. docs/WritingStyleGuide.md sets the voice.
What isn't done yet
- Deployment. Nothing publishes the site anywhere yet, same as the blog.
- Translated pages. Only the interface around each page is translated.
- Versions. There's one version of the docs: the one on
main.
How it compares
| Option | Trade-off |
|---|---|
| A wiki (Notion, Confluence) | Easy to edit, but outside the repo, so nothing ties it to a change |
| A hosted docs platform (Mintlify, GitBook) | Polished, but paid, and your docs live outside your repo |
| README files | In the repo, but no search, navigation, or site to link to |
Bones keeps the docs in git and serves them as static files, on the same design system as the product.
Go deeper
- Fumadocs — the framework under the site.
- Writing docs — adding a page.
- Blogging — the other static site.