writedocs.json

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:

writedocs.json

{
  "name": "Acme Docs",
  "navigation": [
    { "group": "Get started", "pages": ["index", "docs/quickstart"] }
  ]
}

A fuller one:

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 and Tabs, versions, languages and products.

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, Logo and favicon, Fonts and Code themes.

topbar object

Links at the top right of every page. See Topbar, footer and socials.

footer object

Columns of links, and a logo, at the bottom of every page. See Topbar, footer and socials.

socials object

Links to your profiles, shown as icons in the footer. See Topbar, footer and socials.

banner object

A strip above the topbar, for an announcement. See Banner and 404 page.

notFound object

The title and text of the “page not found” page. See Banner and 404 page.

redirects array

Old addresses, and where to send visitors instead. See Redirects.

variables object

Text written once and used in every page as [[name]]. See 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.

seo object

Defaults for the meta tags search engines and social media read. See SEO and sitemap.

contextMenu boolean | array default: true

The Copy page menu on every page, and a Markdown copy of each page. See Contextual menu.

mcp boolean default: true

An MCP server at /mcp, so AI tools can search and read your docs. See MCP server.

api object

How the API reference’s Try it playground sends requests. See Try it playground.

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.

scripts object

External or inline scripts to add to every page. See Custom CSS and 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:

{
  "$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):

{
  "$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.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 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.