# Configuration overview

Every Writedocs site is described by a single `writedocs.json` file at the root of the content directory. The whole file is validated on every `dev` and `build` run — invalid config fails immediately with a readable error instead of producing a broken site.

## Top-level fields

<Parameter name="name" type="string" required>
  Site name — shown in the browser tab title (`Page Title · {name}`) and in the topbar next to the logo.
</Parameter>

<Parameter name="description" type="string">
  Default `<meta name="description">` for pages that don't set their own frontmatter `description`.
</Parameter>

<Parameter name="styles" type="object" default='{ colors: { primary: "#6366f1" } }'>
  Colors, logo, favicon, and code block theming. See [Styles](/docs/configuration/styles/).
</Parameter>

<Parameter name="navigation" type="array or object" required>
  The sidebar/topbar structure. See [Navigation basics](/docs/configuration/navigation-basics/) and [Navigation: tabs, versions, languages, products, dropdowns](/docs/configuration/navigation-advanced/).
</Parameter>

<Parameter name="socials" type="object" default="{}">
  Platform name → profile URL, rendered as a row of icon links in the footer. See [Topbar, footer, and socials](/docs/configuration/topbar-and-socials/).
</Parameter>

<Parameter name="topbar" type="object" default="{ links: [] }">
  Links rendered in the topbar. See [Topbar, footer, and socials](/docs/configuration/topbar-and-socials/).
</Parameter>

<Parameter name="footer" type="object" default="{ columns: [] }">
  Columns of links below the page content. See [Topbar, footer, and socials](/docs/configuration/topbar-and-socials/).
</Parameter>

<Parameter name="api" type="object" default="{ proxy: true }">
  Controls how the "Try it" playground on OpenAPI-powered pages sends requests. See [API settings](/docs/configuration/api-settings/).
</Parameter>

<Parameter name="domain" type="string">
  The site's deployed URL — turns on `sitemap.xml` generation and absolute canonical/Open Graph/Twitter URLs. See [SEO and sitemap](/docs/configuration/seo-and-sitemap/).
</Parameter>

<Parameter name="seo" type="object" default="{}">
  Site-wide meta tag defaults (image, keywords, robots, ...), overridable per page. See [SEO and sitemap](/docs/configuration/seo-and-sitemap/).
</Parameter>

<Parameter name="contextMenu" type="array or false" default="every option">
  The "Copy page" menu next to every eligible page's heading, plus a Markdown copy of every page. On by default; a list picks the options, `false` turns it off. See [Contextual menu](/docs/configuration/context-menu/).
</Parameter>

<Parameter name="redirects" type="array" default="[]">
  Client-side `{ source, destination }` redirects. See [Site-level config](/docs/configuration/site-config/).
</Parameter>

<Parameter name="variables" type="object" default="{}">
  Site-wide `[[key]]` substitution values applied to page prose. See [Site-level config](/docs/configuration/site-config/).
</Parameter>

<Parameter name="banner" type="object" default="off entirely when unset">
  A dismissible strip above the topbar. See [Site-level config](/docs/configuration/site-config/).
</Parameter>

<Parameter name="notFound" type="object" default="{}">
  Custom title/description for the 404 page. See [Site-level config](/docs/configuration/site-config/).
</Parameter>

<Parameter name="scripts" type="object" default="{ head: [], body: [] }">
  Raw third-party `<script>` injection. See [Site-level config](/docs/configuration/site-config/).
</Parameter>

<Parameter name="integrations" type="object" default="{}">
  Curated analytics/chat providers (GA4, Plausible, PostHog, DocsBot, ...). See [Integrations](/docs/configuration/integrations/).
</Parameter>

### `name`

The site name. Shown in the browser tab title (`Page Title · {name}`) and in the topbar next to the logo.

```json
{ "name": "My Docs" }
```

### `description`

Used as the default `<meta name="description">` for pages that don't set their own `description` in frontmatter.

### `styles`

Colors, logo, favicon, and code block theming. See [Styles](/docs/configuration/styles/).

### `navigation`

The sidebar/topbar structure. See [Navigation basics](/docs/configuration/navigation-basics/) for the simple flat-array form, and [Navigation: tabs, versions, languages, products, dropdowns](/docs/configuration/navigation-advanced/) for larger sites.

### `topbar`, `footer`, and `socials`

Topbar links, footer columns of links, and a social-links map (rendered as icons in the footer). See [Topbar, footer, and socials](/docs/configuration/topbar-and-socials/).

### `api`

Controls how the "Try it" playground on OpenAPI-powered pages sends requests. See [API settings](/docs/configuration/api-settings/).

### `domain` and `seo`

`domain` is the site's deployed URL — it turns on `sitemap.xml` generation and absolute canonical/Open Graph/Twitter URLs. `seo` sets site-wide meta tag defaults (image, keywords, robots, ...), overridable per page. See [SEO and sitemap](/docs/configuration/seo-and-sitemap/).

### `contextMenu`

The "Copy page" menu next to every eligible page's heading, plus a Markdown copy of every page at its own URL with `.md` appended. On by default with every option; a list (`["copy", "claude"]`) picks the options, and `false` turns off both the menu and the `.md` copies. See [Contextual menu](/docs/configuration/context-menu/).

<Callout type="tip">
  Every field below is documented with its own JSON example — you can generally copy a snippet directly into your `writedocs.json` and adjust the values.
</Callout>

## Editor autocompletion

The writedocs package includes a JSON Schema for `writedocs.json`: `writedocs.schema.json`. An editor that knows it autocompletes every field, shows what each one does on hover, and underlines anything writedocs won't accept - before you run a build.

When writedocs is installed in the project (`npm install @writedocs/generator`), point `$schema` at it:

```json
{
  "$schema": "./node_modules/@writedocs/generator/writedocs.schema.json",
  "name": "My Docs"
}
```

With a global install, tell your editor where the file is instead. In VS Code, add this to your settings, with the path from `npm root -g`:

```json
"json.schemas": [
  {
    "fileMatch": ["writedocs.json"],
    "url": "file:///<npm root -g>/@writedocs/generator/writedocs.schema.json"
  }
]
```

The schema is generated from the same rules `writedocs validate` uses, so the two agree. One difference: an unknown top-level key is only a warning for `validate`, but the editor underlines it - it's almost always a typo.

## Full reference

Want every field in one place? [`writedocs.full.jsonc`](/writedocs.full.jsonc) is a single annotated file covering every top-level field (all seventeen, from `name` down to `integrations`) and everything nested inside them — types, defaults, and a comment explaining each one. It's JSONC (JSON with comments), so it's meant to read from and copy pieces out of, not to use as your actual `writedocs.json` directly.