Skip to Content
Settlr

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

Pages

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.

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 (with type="info", "warn" or "error")
  • Cards and Card
  • Steps and Step
  • Tabs and Tab
  • Files, Folder and File

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 ![Alt text](/screenshots/name.png); 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.

On this page