docs.json Guide

What is it?

docs.json is the single source of truth for your documentation navigation. It defines tabs, groups, and the ordered list of pages that appear in the sidebar, and it powers previous/next navigation.

• Location: src/app/(pages)/docs.json
• Used by: navigation, left sidebar, previous/next links, and page metadata helpers

File structure

Top‑level fields

• name: Site identifier used in a few places (branding/logging).
• favicon: Path to the favicon under public/.
• navigation.tabs[]: Primary navigation areas in the left sidebar.
• navigation.global.anchors[]: Optional external links rendered globally (e.g., footer or header menus), each with anchor, href, and icon.

Tabs and groups

• tab: The visible tab label in the sidebar (for example, "Guides", "API Reference").
• groups[]: Buckets within a tab. Each group has:
  • group: The visible section label.
  • pages: An ordered list of page items. Each item is either:
    • A string page path (e.g., "quickstart/guide"), or
    • A dropdown object (see below).

Pages

• A string entry is a page path (without .mdx) relative to src/app/(pages).
• The order of items in pages determines:
  • Left sidebar ordering
  • Previous/Next navigation (computed from this order)
• The file must exist as src/app/(pages)/<page>.mdx.
• Titles come from the page frontmatter (title:). If omitted, a title is derived from the filename.

Adding a new page to docs.json

1. Create a markdown file under src/app/(pages) (e.g., src/app/(pages)/quickstart/my-page.mdx).
2. Add frontmatter at the top:

3. Add the page path (without .mdx) to the appropriate pages array in docs.json:

Dropdowns in the pages array

You can insert dropdowns directly into the pages array using a small object with a dropdown label and its own pages list.

Behavior:

• String items render as normal sidebar links.
• Dropdown objects render as a toggleable section titled by dropdown, with their pages indented underneath.
• You can mix pages and dropdowns in any order within the pages array.

API endpoint pages (optional)

If a page represents an API endpoint, include one of the following in the frontmatter:

• openapi: "GET /documents" (preferred)
• api: "GET /documents"

This enables API‑aware UI (method badge, try‑it button, request/response details) and determines HTTP method visualization throughout the navigation. The method color mapping is handled internally.

Icons (optional)

You can set a page icon via page frontmatter:

Icon names map to built‑in icons. See src/lib/sidebar-utils.ts for the available keys (e.g., code, book, file-text, slack, etc.).

Global anchors (optional)

Add external links under navigation.global.anchors:

Common pitfalls

• The pages path must match the markdown path without the .mdx extension.
• Ordering in pages controls Previous/Next; if navigation feels wrong, check order.
• Titles missing in frontmatter will be auto‑generated from filenames (may not look polished).
• Invalid icon names won’t render; use keys defined in src/lib/sidebar-utils.ts.
• If you add a page but don’t see it, ensure both the file exists and docs.json is updated.

Full example

You’re set—edit docs.json to reorganize your docs without touching page code. Changes take effect on the next build/dev reload.