Skip to content
Reed Docs

Project anatomy

What lives in a Reed project, and which parts you commit.

The smallest real Reed project is a config file and a directory of MDX:

docs.json
docs.schema.json
content/
  index.mdx
  quickstart.mdx
openapi/            # only if you reference an OpenAPI spec
  ingestion.yaml
assets/             # only if docs.json references local files
  logo.svg

docs.json

Section titled “docs.json”

Your project root — --dir, default .. It is the single configuration entry point: navigation, colors, typography, SEO, redirects, derived-surface settings. Everything is validated with a strict schema, so an unrecognized top-level key is an error rather than a silent no-op. A field name carried over from another documentation platform will not be quietly ignored.

docs.schema.json

Section titled “docs.schema.json”

A real, self-contained copy of Reed’s JSON Schema, written next to docs.json by reed init. Point $schema at it and your editor gets completion and validation for every field:

json
{
  "$schema": "./docs.schema.json",
  "name": "My Documentation"
}

Commit it like any other project file. It is a copy rather than a node_modules reference on purpose — a node_modules-relative $schema silently fails to resolve under pnpm’s default layout. Re-run reed init after upgrading Reed to refresh it.

$schema is accepted by the schema and otherwise ignored by Reed, so adding, removing or hand-editing it is always safe.

content/

Section titled “content/”

Your MDX pages — --content, default <dir>/content. The path determines the page id. content/authoring/pages.mdx has the id authoring/pages, and that is the string you write in navigation.

The derivation is not a bare path-minus-extension: segments are slugified, a nested index collapses to its directory, and a frontmatter slug overrides both. See Navigation.

openapi/

Section titled “openapi/”

Optional. Spec files referenced by path from api.specs in docs.json. A project with no api block never needs this directory.

assets/

Section titled “assets/”

Optional, and the name is a convention rather than a rule. Local files referenced from docs.json — logo, favicon, customCss, seo.ogImage — are resolved relative to the directory docs.json lives in, so any layout works as long as the paths match.

.reed/

Section titled “.reed/”

A build cache Reed creates and manages. Gitignored, never committed. Deleting it costs you a slower next build and nothing else.