--- title: Concepts description: How docs.json, content, templates, the compile pipeline and the derived surfaces fit together. --- Reed is a compiler. It reads one `docs.json` and a directory of MDX, checks them, and writes a static site plus the machine-readable surfaces that belong with it. This page names the moving parts and shows how they connect. The [Glossary](/docs/glossary) defines each term in a sentence or two. ## The inputs A Reed project has four kinds of input. All of them live in your repository. **`docs.json`** is the single configuration file. Navigation, template, colors, typography, SEO, redirects and generator settings all live here. It is validated against a strict schema, so an unknown key is an error, not a silent no-op. See [Project anatomy](/docs/project-anatomy). **The content directory** holds your pages, one `.mdx` file each. The path is the page id: `content/authoring/pages.mdx` is `authoring/pages`. Segments are slugified, a nested `index` collapses to its directory, and a frontmatter `slug` overrides both. Files starting with `_` and anything under a dot-prefixed directory are not loaded. See [Navigation](/docs/authoring/navigation). **Assets** are local files that `docs.json` references: `logo`, `favicon`, `customCss`, `seo.ogImage`. They resolve relative to the directory `docs.json` sits in. Reed checks that each one exists. **OpenAPI specs** are optional. Declare them by name under `api.specs`, and Reed generates an endpoint page per operation. No MDX file exists for those pages. See [OpenAPI specs](/docs/api/specs). ## Pages and navigation Navigation is a list of tabs. Each tab holds groups, and each group holds pages. A page enters navigation as a `PageRef`, a string naming its page id. The relationship is strict in both directions: - A `PageRef` that names no file is an error at `reed check`. - A content file that no `PageRef` names is an orphan, and also an error at `reed check`: `content-page-not-in-navigation`. A file whose own name starts with `_` is not a page and is exempt. There are no hidden pages. Every page you ship is in navigation, so every new page arrives with a navigation change in the same pull request. ## Templates `template` picks the visual design: `mint`, `rapide` or `black`. `mint` is the fully featured design system. `rapide` and `black` are minimal templates that implement the same interface. A template owns its baseline: a stylesheet with its own value for every dimension. Your design values in `docs.json` are tokens. Reed turns them into CSS custom properties and layers them above the baseline. Your `customCss` goes above that. The order is fixed: L0 token contract, L1 template baseline, L2 generated tokens, L3 `customCss`. See [Colors and the CSS cascade](/docs/design/colors). The component catalog is the same under every template. Switching templates changes how pages look, never whether they build. See [Templates](/docs/design/templates). ## The compile pipeline Every command that reads your project runs the same front half. `reed build` adds the back half. `docs.json` is parsed against the schema. A failure stops here, before anything else runs. The named template is loaded and its defaults are merged under your values. A token the template cannot honor is reported as a warning, and the template's baseline keeps control of that dimension. Static checks run over the config and every page. Page references resolve, components exist in the catalog and carry their required props, assets and specs are present and parse. Problems are reported as `DS-*` codes and a few named errors. Build only. Reed generates a throwaway Astro and Starlight project under `.reed/`, installs its pinned dependencies from the local store with no network, and runs the site build inside it. Build only. The result replaces `--out` in one staged swap. The output directory is never a mix of old and new files, even when a build fails partway. `check` and `build` share the first three steps, so they run the same schema and content validation. Two problems surface only at build: a page no `PageRef` names, and a broken local import. See [Diagnostics](/docs/reference/diagnostics). ## `check`, `dev` and `build` | Command | Runs | Writes | Network | |---|---|---|---| | `reed check` | Steps 1–3 | No site output | Never | | `reed dev` | The same compile path, then a live preview server | No output directory. Serves pages and their `.md` mirrors | None after `prefetch` | | `reed build` | All five steps | The complete site in `--out` | None after `prefetch` | `dev` does not write the build-only files: no `llms.txt`, no `sitemap-index.xml`, no `robots.txt`, no `_headers`. To inspect those, run `reed build` and read the output directory. See [reed dev](/docs/reference/cli/dev) and [Build output](/docs/ship/output). The strict flags gate `check` and `build`. `--strict-components` escalates `DS-D*` warnings to errors. `--strict-tokens` escalates every other warning. `dev` is looser: it ignores `--strict-components`, prints `--strict-tokens` escalations as errors without acting on them, and refuses to start only on diagnostics that are errors in their own right. ## Derived surfaces A website is one view of your docs. Reed emits the others from the same intermediate representation, the Doc IR, so no surface is scraped from another. | Surface | Produced by | Lands in | |---|---|---| | `llms.txt` | every `reed build` | the output directory | | `.md` mirror per page | every `reed build` (and served by `dev`) | the output directory | | MCP server source | `reed mcp generate` | your repository | | Skill pack | `reed skill generate` | your repository | The MCP server and the Skill pack need their own config blocks and are not part of a deploy. Their tool and method names come from one capability identity per operation, so the two surfaces always name an operation the same way. See [One source, every surface](/docs/derived/overview). ## The offline guarantee `reed prefetch` is the only command that touches the network. Run it once per machine. It fills two caches: the pinned dependency store at `REED_STORE_DIR`, and Corepack's cache of the pinned package-manager binary. After that, `dev` and `build` need no network. `check` never needs it, even with no prefetch at all. The guarantee covers exactly the platform, architecture and libc that prefetch ran on. In CI, restore both caches or the build quietly reaches out. See [Offline builds in CI](/docs/ship/ci-offline). ## The `.reed/` directory Reed creates `.reed/` in your project root and manages it. It holds the build's working files and caches, including the per-build Astro project, which is deleted after its output is published. Gitignore it and never commit it. Deleting it costs one slower build and nothing else. It is not the dependency store. That lives at `REED_STORE_DIR`, outside any one project, and is shared by every Reed project on the machine. ## A compiler, not a platform Reed runs where you run it: your terminal, your CI. There is no hosted build, no dashboard, no `reed deploy` and no npm package yet. Deploying is uploading the output directory to any static host. The output never calls back to Reed. Search runs in the browser against an index shipped with the pages. If Reed disappears, the site you built keeps working. What does not exist yet is listed on the [Roadmap](/docs/roadmap), and only there.