# 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.

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

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

<Callout type="note">
  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.
</Callout>

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:

```json
{
  "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:

```json
{
  "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 or is listed in `navigation`:

```
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
```

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

A file with no frontmatter block that `navigation` doesn't list either (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/`, every folder whose name starts with a dot (`.git`, `.github`, ...), and anything listed in a `.mintignore` file 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.)

<Callout type="tip">
  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` serves at `/docs/`, not `/`. In `writedocs.json` it can be listed either as `"docs"` or, as Mintlify projects often write it, `"docs/index"` - both name the same page. Put your home page at the project root if you want it at `/`.
</Callout>

<Callout type="note">
  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.
</Callout>

## Beyond a single sidebar

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