Concepts

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 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.

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.

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.

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.

The component catalog is the same under every template. Switching templates changes how pages look, never whether they build. See Templates.

The compile pipeline

Every command that reads your project runs the same front half. reed build adds the back half.

1. Schema parse

   docs.json is parsed against the schema. A failure stops here, before anything else runs.

2. Template resolution

   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.

3. Diagnostics

   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.

4. Astro and Starlight synthesis

   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.

5. Atomic output

   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.

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 and Build 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.

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.

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, and only there.