Navigation basics

The simplest navigation is a flat array — one implicit sidebar. Each entry is one of three things.

Page slugs

A string matching a page’s file, without its extension — its path relative to the project root. "docs/guides/components" matches docs/guides/components.mdx; "about" matches about.mdx at the project root.

{
  "navigation": ["index", "docs/getting-started"]
}

Groups

An object with group (the heading shown above its pages) and pages (an array that can itself contain slugs, further nested groups, or links). Groups can nest inside each other to any depth.

{
  "navigation": [
    { "group": "Getting Started", "pages": ["index", "docs/getting-started"] },
    {
      "group": "Guides",
      "pages": [
        "docs/guides/components",
        {
          "group": "Advanced",
          "pages": ["docs/guides/theming", "docs/guides/deployment"]
        }
      ]
    }
  ]
}

Only the outermost group level renders as a static, non-collapsible section title. Any group nested inside another (like “Advanced” above) renders as a collapsible row instead, defaulting open whenever the active page is inside it.

A group can also link its own label to a page, via page — clicking the group’s heading navigates there, independent of the chevron that expands/collapses its children:

{
  "group": "Webhooks",
  "page": "docs/api/webhooks/overview",
  "pages": ["docs/api/webhooks/signature-verification"]
}

Breadcrumbs

Automatic, zero-config — no field to set. Any page nested inside a group gets a breadcrumb trail above its title: a home icon (always first, always links to /), then one crumb per enclosing group (root first), linking to that group’s own page (via page) when it has one or rendering as plain text when it doesn’t. The current page itself is never in the trail — that’s already the heading right below it.

A page sitting at the top level of navigation with no enclosing group at all — a bare page slug directly in the array, not inside any group — gets no breadcrumb bar at all, home icon included.

Links

A bare external link sitting directly in a pages array, alongside page slugs and groups:

{
  "navigation": [
    "index",
    { "label": "Support", "href": "https://support.example.com" }
  ]
}

Ordering

The order in navigation determines both sidebar order and the automatic previous/next links at the bottom of each page — reorder navigation to reorder those too.

Pages can live anywhere

docs/ is a convention, not a requirement — it’s a plain folder, scanned and referenced exactly the same as any other. A .md/.mdx file becomes a page — and can be referenced from navigation — no matter where it lives in your project, as long as it has a frontmatter block:

my-docs/
├── writedocs.json
├── index.mdx          # "index" - the home page, served at "/"
├── about.mdx           # "about" - also at the project root
├── legal/
│   └── terms.mdx      # "legal/terms" - a custom folder
└── docs/
    └── getting-started.mdx   # "docs/getting-started" - same "docs/" prefix any folder gets

{
  "navigation": ["index", "about", "legal/terms", "docs/getting-started"]
}

A file with no frontmatter block at all (a plain README, notes, anything not meant to be a page) is left alone — it’s never turned into a route. node_modules/, dist/, public/, and Writedocs’s own .astro build directory are never scanned. (Writedocs’ own cache and any OpenAPI-generated files live outside your project entirely, in a system temp directory — dev/build never write anything into your project folder for you to manage.)

The home page (served at /) is whichever page’s file id is exactly "index" - in practice, an index.mdx at the project root. A nested index.mdx (docs/index.mdx, docs/guides/index.mdx, …) drops its own /index segment from its file id instead, the same rule Astro applies to every folder - so docs/index.mdx is referenced as "docs" and serves at /docs/, not /. Put your home page at the project root if you want it at /.

See docs.json-examples/00-kitchen-sink/ in the Writedocs repo for a complete, buildable example: about.mdx/signin.mdx at the project root, legal/terms.mdx in a custom nested folder, and ordinary pages inside docs/, all referenced side by side in the same “More” navigation group.

For anything past one flat sidebar — multiple tabs, a version switcher, a language switcher — see Navigation: tabs, versions, languages, products, dropdowns. For turning a group into an auto-generated API reference from an OpenAPI spec, see API Reference (OpenAPI).