Docs.json

Format and Structure

The docs.json Configuration File

The docs.json file controls the structure and navigation of your deployed documentation site. This file must be properly formatted and include all pages you want to make visible.

Any markdown files not referenced in docs.json will not appear on the documentation site.

Required Format

Your docs.json must be valid JSON with the following structure:

docs.json

Structure Requirements

The following structure must be followed for your docs.json to be valid:

Root object must contain a navigation property
navigation.tabs must be an array with at least one tab
Each tab must have:
- tab (string): The tab name displayed in navigation
- groups (array): At least one group containing pages
Each group must have:
- group (string): The group name displayed as a section header
- pages (array): Array of page path strings
global (optional): Contains global configuration like anchors

Page Path Format

Page paths in the pages array must match the actual file locations in your documentation repository:

Format: "generated/{filename}" where {filename} is the markdown file name without the .mdx extension
Example: If your file is getting-started.mdx, the page path is "generated/getting-started"
Paths are relative to the docs/ directory

Structuring Your Sidebar

You can customize the sidebar navigation by modifying the tabs and groups structure. Each tab creates a top-level navigation section, and each group creates a collapsible subsection within that tab.

Single Tab with Multiple Groups

Single Tab Example

This creates a single "Documentation" tab with two collapsible sections: "Getting Started" and "Advanced".

Multiple Tabs

Multiple Tabs Example

This creates two separate tabs ("Guides" and "API"), each with their own groups and pages. Users can switch between tabs to access different sections of documentation.

Validation Rules

Your docs.json will be validated against these rules:

Must be valid JSON syntax
Must contain navigation.tabs as an array with at least one tab
Each tab must have a string "tab" field and a "groups" array
Each group must have a string "group" field and a "pages" array
Each entry in pages must be a string representing a valid file path

If validation fails, you'll receive specific error messages indicating what needs to be fixed.

Automatic Generation

When you generate documents, they are automatically added to the docs.json. However the documents are put into the first available tab in the docs.json so you will most likely want to move it to your liking

Important Notes

docs.json cannot be deleted, moved, or renamed in the editor
The file is locked to prevent accidental corruption of your navigation structure
Any changes to docs.json are immediately reflected in the sidebar navigation when deployed

Generating Themes