---
title: Project anatomy
description: 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`

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`

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/`

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](/docs/authoring/navigation).

## `openapi/`

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

## `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/`

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