# Maintaining these docs

https://exo.now/docs/contributing

> How the Exo docs are built, where the content lives, and how to add or change a page.



## Framework: Fumadocs [#framework-fumadocs]

The docs are built with [Fumadocs](https://fumadocs.dev) (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 [#adding-or-changing-a-page]

1. Add or edit an `.mdx` file under `content/docs/`. Frontmatter needs `title` and should include
   a one-sentence `description`.
2. List new pages in the folder's `meta.json` to control their position in the sidebar.
3. 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 on `staging`, so the same link works in the repository browser.
4. Cite the source for every fact. If the repository does not record something, write **TBD**.
5. Merge to `staging` and review the page at [https://staging.exo.now/docs](https://staging.exo.now/docs). Docs are only ever reviewed on Staging.

## Components available in MDX [#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 [#design-rules]

The docs follow the [Structured Liquidity design standard](../../docs/design-standard.md). 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 [#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.