About these docs
Maintaining these docs
How the Exo docs are built, where the content lives, and how to add or change a page.
Framework: Fumadocs
The docs are built with Fumadocs (MIT), a documentation framework native
to the Next.js App Router. They are served by the existing Exo Next.js app at /docs, so they
share its build, Docker image, Railway service, and staging → production path. There is no second
deployment.
| Piece | Location |
|---|---|
| Authored pages (MDX) | content/docs/** |
| Sidebar order | meta.json in each folder of content/docs |
| Decision records | docs/adr/*.md, rendered in place under /docs/adr/* |
| Roadmap board | roadmap/roadmap.json, rendered on /docs/roadmap |
| Source wiring | src/lib/docs/source.ts (Fumadocs MDX macro API, no codegen step) |
| Route and layout | src/app/(docs)/, a root layout separate from the landing page |
| Exo theme | src/app/(docs)/docs.css, which maps Fumadocs tokens onto the canonical Exo tokens |
| MDX components | src/components/Docs/ |
| Search | GET /api/docs-search, a static index over every page including the ADRs |
Adding or changing a page
- Add or edit an
.mdxfile undercontent/docs/. Frontmatter needstitleand should include a one-sentencedescription. - List new pages in the folder's
meta.jsonto control their position in the sidebar. - Link to other pages or repository files with relative paths, for example
../../../docs/ai-routing.md. Links to docs pages become in-site links, and links to other repo files open onstaging, so the same link works in the repository browser. - Cite the source for every fact. If the repository does not record something, write TBD.
- Merge to
stagingand review the page at https://staging.exo.now/docs. Docs are only ever reviewed on Staging.
Components available in MDX
| Component | Use |
|---|---|
<Callout> | Notes, warnings, and known inconsistencies between sources |
<Cards> / <Card> | Section overviews |
<Steps> / <Step> | Ordered procedures |
<Tabs> / <Tab> | Alternatives, such as staging versus production values |
<StackFacts> | The platform panel on each stack page, read from src/platform/integrations/catalog.ts |
<AdrIndex> | The list of decision records |
<RoadmapBoard> | The roadmap board |
Design rules
The docs follow the Structured Liquidity design standard. The
theme introduces no new colors, radii, or fonts: docs.css points Fumadocs' semantic tokens at
the Exo tokens defined in src/app/(frontend)/globals.css, and the navigation uses the Exo layer
mark from src/components/Logo. Light is the default and dark is the alternate, sharing the
landing page's theme preference.
Checks
pnpm check covers the docs: tsc type-checks the MDX wiring, pnpm lint runs ESLint plus the
Structured Liquidity and visual-vocabulary gates, and pnpm build compiles every page statically. A broken
MDX file fails the build.
Source: content/docs/contributing.mdx