WritedocsWritedocs

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

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.

contextMenuobjectdefault: off entirely when unset

Turns on a “Copy page” dropdown next to every eligible page’s heading, plus a raw-Markdown route for every page. 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

Turns on a “Copy page” dropdown next to every eligible page’s heading, plus a raw-Markdown route for every page at its own URL with .md appended. Off entirely (no dropdown, no .md routes) unless this field is set. 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.

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.