Writing docs

Every Remy app keeps its docs the same way, so the shared tasks and the Fumadocs CLI work in each one. There are two docs sites, served by the docs Worker (the docs/ app, apart from the app Worker): the guide for the app's users at /docs, and these developer docs at /dev. Each has its own languages, search, llms.txt and Ask AI folder.

Who each part is forCopy Anchor Link

The docs have three parts, and each is written from one reader's side. Google's AI Mode, Gemini and every other assistant tell them apart only by what the pages say, so keep them apart:

• A page that needs the other side links to it in one line ("Building it? The developer docs.").
• Each part's home page opens by saying who it is for; its titles end with the part's name (docs.config.ts, titles), and so do its llms.txt and MCP server (Docs in your AI tools).
• The parts, their readers, llms files and MCP servers are one list, src/lib/sections.ts.

LayoutCopy Anchor Link

• i18n.json is the site's languages: defaultLanguage and languages. The site's URLs, language menu, search and translation tasks all read it. The two sites' lists differ: developer docs are translated only into the languages we support developers in.
• meta.json is the site's navigation: pages sets the order, "---Heading---" starts a section, "[Title](https://…)" is a link out.
• A translation sits beside its page: index.es.md beside index.md, at /dev/es/.
• The guide's pictures and videos are in docs/public/media, referenced by URL (/media/formats.png); the developer docs have Mermaid diagrams and type tables; the API reference is its own section at /reference, made from the oRPC contract.

How a page reaches the readerCopy Anchor Link

flowchart LR
  A["docs/content/*.md, *.mdx"] --> B["fumadocs-mdx macro"]
  B --> C["loader: src/lib/source.ts"]
  C --> D["Docs pages: /docs, /dev"]
  C --> E["Search: /api/search/dev"]
  C --> F["/dev/llms.txt and .md pages"]
  C --> G["MCP server: /api/mcp/dev"]
  C --> H["Social images: /og/dev/..."]
  I["oRPC contract"] --> J["fumadocs-openapi"] --> K["API reference: /reference"]

FrontmatterCopy Anchor Link

Every page starts with a title and a description. The description is the page's summary in search results, llms.txt and link previews.

---
title: "Formats"
description: "How dates, numbers, currency and direction change with the language you choose."
---

Pictures and videosCopy Anchor Link

![The Formats page in English](/media/formats.png)

ComponentsCopy Anchor Link

In .mdx pages: <Callout> (or :::note, :::warning in any page), <Cards> and <Card>, <Tabs> and <Tab>, <Steps> and <Step>, <Accordions> and <Accordion>, <Files>, <Folder> and <File>, a ```mermaid diagram, and a type table read from our TypeScript:

The Fumadocs CLICopy Anchor Link

npm run docs:cli -- feature <name> (remy-auth only) runs the pinned Fumadocs CLI in the shared docs Worker, packages/ui/src/docs; its cli.json maps the folders there, and what it writes is a change to the package, reviewed like any other. Apps take the Worker from the package and never run it.

TranslationsCopy Anchor Link

Write English only. dev:land translates on main after the landing, one writer at a time (translations: one writer); npx remy i18n check docs lists what each language still needs.