Navigation

The navigation object in dory.json defines the sidebar structure. Navigation is organized into three levels: tabs, groups, and pages.

Structure#

JSON

"navigation": {
  "tabs": [
    {
      "tab": "Documentation",
      "groups": [
        {
          "group": "Getting Started",
          "pages": [
            "introduction",
            "installation",
            "quick-start"
          ]
        },
        {
          "group": "Components",
          "pages": [
            "components/overview",
            "components/code-blocks"
          ]
        }
      ]
    },
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Endpoints",
          "pages": [
            "api/users",
            "api/workspaces"
          ]
        }
      ]
    }
  ]
}

Tabs#

Tabs appear at the top of the sidebar. Use multiple tabs to separate major sections of your documentation.

JSON

{
  "tab": "Documentation",
  "groups": [...]
}

Field	Type	Description
`tab`	`string`	Tab label shown in the sidebar header.
`groups`	`Group[]`	Navigation groups within this tab.

Groups#

Groups are collapsible sections within a tab. They appear as labeled sections in the sidebar.

JSON

{
  "group": "Getting Started",
  "pages": ["introduction", "installation"]
}

Field	Type	Description
`group`	`string`	Group label.
`pages`	`string[]`	List of page paths within the group.

Pages#

Pages are references to MDX files. Use paths relative to the docs directory root, without the .mdx extension.

JSON

"pages": [
  "introduction",
  "getting-started/installation",
  "components/code-blocks"
]

A path like "components/code-blocks" maps to docs/components/code-blocks.mdx.

Note

Page paths are case-sensitive and must exactly match the filename (without .mdx). Use lowercase with hyphens for consistency.

Single-Tab Setup#

For smaller documentation sites, one tab is enough:

JSON

"navigation": {
  "tabs": [
    {
      "tab": "Docs",
      "groups": [
        {
          "group": "Overview",
          "pages": ["introduction"]
        },
        {
          "group": "Guides",
          "pages": ["guides/setup", "guides/deployment"]
        }
      ]
    }
  ]
}

Multi-Tab Setup#

Separate documentation types with multiple tabs:

JSON

"navigation": {
  "tabs": [
    {
      "tab": "Guides",
      "groups": [
        {
          "group": "Getting Started",
          "pages": ["introduction", "installation"]
        }
      ]
    },
    {
      "tab": "API Reference",
      "groups": [
        {
          "group": "Users",
          "pages": ["api/create-user", "api/get-user", "api/delete-user"]
        }
      ]
    },
    {
      "tab": "SDKs",
      "groups": [
        {
          "group": "Client Libraries",
          "pages": ["sdks/javascript", "sdks/python", "sdks/go"]
        }
      ]
    }
  ]
}

Set version in dory.json to show the version card at the top of the sidebar. A page entry can be an object with a badge, which renders as a small label after the page name.

dory.json

json

1{
2  "version": "1.0.8 · Latest",
3  "navigation": {
4    "tabs": [{
5      "tab": "Documentation",
6      "groups": [{
7        "group": "Writing Docs",
8        "pages": ["introduction", { "page": "components/overview", "badge": "New" }]
9      }]
10    }]
11  }
12}

API reference pages show their method in the sidebar automatically, taken from the page's openapi or asyncapi frontmatter.

Page Frontmatter#

Each MDX page should include frontmatter with title and description. These are used for the page title, meta tags, and breadcrumbs:

MDX

---
title: 'Installation'
description: 'Install and configure Dory for your project.'
---

# Installation

Tip

Keep title concise (2–5 words). The description is used for SEO meta tags and appears in search results, so make it a full sentence.

Lead Paragraph and Metadata Strip

Add a lead string to show a larger introductory paragraph directly under the page title. Add a meta map to show a row of labelled facts below it. Keys are the labels and values are shown as written. YAML dates such as 2026-10-12 render as 12 Oct 2026.

MDX

---
title: 'Introduction'
description: 'What Dory is and how to get started.'
lead: 'Dory turns MDX pages into a documentation site with navigation, search, and interactive components.'
meta:
  License: MIT
  Updated: 2026-10-12
  Read: 4 min
---

Pages without lead or meta show neither.

Was this page helpful?

Structure#

Tabs#

Groups#

Pages#

Single-Tab Setup#

Multi-Tab Setup#

Sidebar Extras#

Page Frontmatter#

Lead Paragraph and Metadata Strip