Writing docs
How this documentation site is built and how to add pages to it.
These docs are apps/docs, a Next.js app built with
Fumadocs. Run it with:
pnpm dev:docs # http://localhost:3001Pages
Pages are MDX files in apps/docs/content/docs. The URL follows the path:
guide/friends.mdx is /docs/guide/friends, and a folder's index.mdx is
the folder's URL.
Each page starts with frontmatter:
---
title: Friends
description: One line shown under the title and in search results.
icon: User
---icon is the name of a Lucide icon.
Navigation
The sidebar's order comes from meta.json files. The root one splits the
docs into the Using Settlr and Development sections; each folder's
meta.json lists its pages in order. Add a new page's file name (without
.mdx) to the folder's meta.json.
Components
Besides Markdown, pages can use these components without importing them
(registered in apps/docs/components/mdx.tsx):
Callout(withtype="info","warn"or"error")CardsandCardStepsandStepTabsandTabFiles,FolderandFile
Link between pages with absolute URLs (/docs/guide/groups) or relative file
paths (./groups.mdx).
Screenshots
Screenshots live in apps/docs/public/screenshots and are embedded with
; readers can click one to see it full
size. Keep them consistent with the existing ones:
- the dark theme at 1440×900, with the sidebar expanded;
- a demo account with realistic sample data, never a real person's account or email;
- alt text that says what the screenshot shows.
The current set was taken on the dev deployment with the demo account
delivered+alex@resend.dev (Resend's test inbox: read its sign-in codes with
pnpm exec convex data --component betterAuth verification). Retake a
screenshot when the page it shows changes.
For AI tools
Every page is also served as Markdown: append .md to its URL, or request
it with Accept: text/markdown. /llms.txt lists the pages and
/llms-full.txt has all of them in one file.
Style
Write for someone using the feature: say what it does and how, in short sentences, with the button and page names as they appear in the app. When the app changes, update the matching page in the same pull request.