WritedocsWritedocs

Configuration overview

View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page
Connect to CursorUse these docs in CursorConnect to VS CodeUse these docs in VS Code

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

namestringrequired

Site name — shown in the browser tab title (Page Title · {name}) and in the topbar next to the logo.

descriptionstring

Default <meta name="description"> for pages that don’t set their own frontmatter description.

stylesobjectdefault: { colors: { primary: "#6366f1" } }

Colors, logo, favicon, and code block theming. See Styles.

navigationarray or objectrequired

The sidebar/topbar structure. See Navigation basics and Navigation: tabs, versions, languages, products, dropdowns.

socialsobjectdefault: {}

Platform name → profile URL, rendered as a row of icon links in the footer. See Topbar, footer, and socials.

topbarobjectdefault: { links: [] }

Links rendered in the topbar. See Topbar, footer, and socials.

footerobjectdefault: { columns: [] }

Columns of links below the page content. See Topbar, footer, and socials.

apiobjectdefault: { proxy: true }

Controls how the “Try it” playground on OpenAPI-powered pages sends requests. See API settings.

domainstring

The site’s deployed URL — turns on sitemap.xml generation and absolute canonical/Open Graph/Twitter URLs. See SEO and sitemap.

seoobjectdefault: {}

Site-wide meta tag defaults (image, keywords, robots, …), overridable per page. See SEO and sitemap.

contextMenuarray or falsedefault: 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.

redirectsarraydefault: []

Client-side { source, destination } redirects. See Site-level config.

variablesobjectdefault: {}

Site-wide [[key]] substitution values applied to page prose. See Site-level config.

bannerobjectdefault: off entirely when unset

A dismissible strip above the topbar. See Site-level config.

notFoundobjectdefault: {}

Custom title/description for the 404 page. See Site-level config.

scriptsobjectdefault: { head: [], body: [] }

Raw third-party <script> injection. See Site-level config.

integrationsobjectdefault: {}

Curated analytics/chat providers (GA4, Plausible, PostHog, DocsBot, …). See Integrations.

name

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

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

The sidebar/topbar structure. See Navigation basics for the simple flat-array form, and Navigation: tabs, versions, languages, products, dropdowns for larger sites.

Topbar links, footer columns of links, and a social-links map (rendered as icons in the footer). See Topbar, footer, and socials.

api

Controls how the “Try it” playground on OpenAPI-powered pages sends requests. See 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.

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.

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.

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:

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