# writedocs.json

> For the complete documentation index, see [llms.txt](https://preview.writedocs.io/llms.txt).

The file that describes your site - every top-level field, with links to the details.

Every Writedocs site is described by one `writedocs.json` file, in the project's root folder. It's checked on every `writedocs dev` and `writedocs validate` run: a mistake is reported with its line and what to write instead, rather than turning into a broken site.

Only `name` and `navigation` are required:

```json title="writedocs.json"
{
  "name": "Acme Docs",
  "navigation": [
    { "group": "Get started", "pages": ["index", "docs/quickstart"] }
  ]
}
```

A fuller one:

```json title="writedocs.json"
{
  "$schema": "https://preview.writedocs.io/schema.json",
  "name": "Acme Docs",
  "description": "Guides and API reference for Acme.",
  "domain": "docs.acme.com",
  "styles": {
    "colors": { "primary": "#0f766e", "dark": { "primary": "#2dd4bf" } },
    "logo": { "light": "/images/logo-light.svg", "dark": "/images/logo-dark.svg" },
    "favicon": "/images/favicon.svg"
  },
  "navigation": {
    "tabs": [
      { "tab": "Guides", "pages": ["index", "docs/quickstart"] },
      { "tab": "API reference", "pages": [{ "group": "Endpoints", "openapi": { "src": "openapi.yaml", "path": "/api" } }] }
    ]
  },
  "topbar": { "links": [{ "label": "Dashboard", "href": "https://app.acme.com" }] },
  "socials": { "github": "https://github.com/acme" },
  "integrations": { "plausible": { "domain": "docs.acme.com" } }
}
```

## Top-level fields

**`name`** `string` required

The site's name. Shown in the browser tab (`Page title · Acme Docs`), and in the topbar when there's no logo.

**`navigation`** `array | object` required

The pages and how they're organized: a sidebar of groups, or tabs, versions, languages, products and dropdowns. See [Navigation basics](https://preview.writedocs.io/docs/configuration/navigation-basics/) and [Tabs, versions, languages and products](https://preview.writedocs.io/docs/configuration/navigation-advanced/).

**`description`** `string`

The site's description: the `<meta name="description">` of pages without a `description` of their own, and the summary at the top of `llms.txt`.

**`styles`** `object`

Colors, logo, favicon, fonts, code themes, navbar and background. See [Colors and backgrounds](https://preview.writedocs.io/docs/configuration/colors/), [Logo and favicon](https://preview.writedocs.io/docs/configuration/logo-and-favicon/), [Fonts](https://preview.writedocs.io/docs/configuration/fonts/) and [Code themes](https://preview.writedocs.io/docs/configuration/code-themes/).

**`topbar`** `object`

Links at the top right of every page. See [Topbar, footer and socials](https://preview.writedocs.io/docs/configuration/topbar-and-socials/#topbar).

**`footer`** `object`

Columns of links, and a logo, at the bottom of every page. See [Topbar, footer and socials](https://preview.writedocs.io/docs/configuration/topbar-and-socials/#footer).

**`socials`** `object`

Links to your profiles, shown as icons in the footer. See [Topbar, footer and socials](https://preview.writedocs.io/docs/configuration/topbar-and-socials/#socials).

**`banner`** `object`

A strip above the topbar, for an announcement. See [Banner and 404 page](https://preview.writedocs.io/docs/configuration/banner-and-404/#banner).

**`notFound`** `object`

The title and text of the "page not found" page. See [Banner and 404 page](https://preview.writedocs.io/docs/configuration/banner-and-404/#404-page).

**`redirects`** `array`

Old addresses, and where to send visitors instead. See [Redirects](https://preview.writedocs.io/docs/configuration/redirects/).

**`variables`** `object`

Text written once and used in every page as `[[name]]`. See [Variables](https://preview.writedocs.io/docs/content/variables/).

**`domain`** `string`

The address the site is published at. Turns on `sitemap.xml` and full URLs in links shared on social media. See [SEO and sitemap](https://preview.writedocs.io/docs/configuration/seo-and-sitemap/#domain).

**`seo`** `object`

Defaults for the meta tags search engines and social media read. See [SEO and sitemap](https://preview.writedocs.io/docs/configuration/seo-and-sitemap/#seo).

**`contextMenu`** `boolean | array` default: `true`

The **Copy page** menu on every page, and a Markdown copy of each page. See [Contextual menu](https://preview.writedocs.io/docs/configuration/context-menu/).

**`mcp`** `boolean` default: `true`

An MCP server at `/mcp`, so AI tools can search and read your docs. See [MCP server](https://preview.writedocs.io/docs/configuration/mcp/).

**`api`** `object`

How the API reference's **Try it** playground sends requests. See [Try it playground](https://preview.writedocs.io/docs/configuration/api-settings/).

**`integrations`** `object`

Analytics and an AI chat widget, turned on with an ID: Google Analytics 4, Google Tag Manager, Plausible, Fathom, PostHog, Umami and Ask AI. See [Integrations](https://preview.writedocs.io/docs/configuration/integrations/).

**`scripts`** `object`

External or inline scripts to add to every page. See [Custom CSS and scripts](https://preview.writedocs.io/docs/configuration/custom-code/#scripts).

**`$schema`** `string`

Where your editor finds the file's schema, for autocompletion. See below.

A key that isn't one of these is reported as a warning by `writedocs validate` - it's almost always a typo.

## Editor autocompletion

Writedocs has a JSON Schema for `writedocs.json`. An editor that knows about it completes every field, explains each one on hover, and underlines anything Writedocs won't accept - before you preview the site.

Point `$schema` at it, as the first line of `writedocs.json`:

```json
{
  "$schema": "https://preview.writedocs.io/schema.json",
  "name": "Acme Docs"
}
```

VS Code, Cursor and JetBrains editors read `$schema` with no setup. The schema at that address is kept up to date with Writedocs.

### The schema of your installed version

The schema also comes with Writedocs, as `writedocs.schema.json` - matching the version you have installed, and available offline. With Writedocs installed in the project (`npm install @writedocs/generator`):

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

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

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

The schema follows the same rules as `writedocs validate`, so the two agree - except that the editor underlines an unknown top-level key, which `validate` only warns about.

## Every field in one file

[`writedocs.full.jsonc`](https://preview.writedocs.io/writedocs.full.jsonc) is an annotated `writedocs.json` with every field, its type and default, and a comment on each. It's for reading and copying from - the comments make it JSONC, not a file to use as it is.