Docusaurus Nav Command

Converts a Docusaurus sidebars.js file into Mintlify navigation JSON, ready to paste into docs.json.

Usage

writechoice docusaurus nav <file> [options]

Arguments

Argument	Description
<file>	Path to the Docusaurus sidebars.js (or sidebars.ts) file

Options

Option	Description	Default
--prefix <path>	Prepend a path prefix to every page ID (e.g. mintlify)	—
--docs-dir <dir>	Docs folder used to expand autogenerated items	docs/ next to sidebars.js
-o, --output <file>	Write result to this file instead of stdout	nav.json
--quiet	Suppress terminal output	false

Output Format

The output structure depends on how many sidebars are defined:

Sidebars count	Output structure
One sidebar	{ anchors: [{ anchor, pages }] }
Multiple sidebars	{ tabs: [{ tab, pages }] }

This JSON is designed to be merged into or used as the navigation value in docs.json.

Supported Item Types

Docusaurus type	Handled as
String (bare doc ID)	Page path string
{ type: 'doc', id }	Page path string
{ type: 'category', label, items }	{ group, pages } object
{ type: 'autogenerated', dirName }	Expanded by reading the docs folder
{ type: 'link' }	Skipped (external links)
{ type: 'html' }	Skipped (decorative separators)
{ type: 'ref' }	Treated as a doc ID

Autogenerated expansion

When a sidebar contains { type: 'autogenerated', dirName: 'faq' }, the command walks the corresponding directory in the docs folder and builds the equivalent structure:

• Reads _category_.json in subdirectories for folder label and position
• Reads sidebar_position from each file's frontmatter for ordering
• Falls back to alphabetical sort when positions are equal or absent
• Skips files and directories whose names start with _

Examples

# Convert sidebars.js, write result to nav.json
writechoice docusaurus nav ./my-site/sidebars.js

# Add a prefix so all page IDs start with "mintlify/"
writechoice docusaurus nav ./my-site/sidebars.js --prefix mintlify

# Write to a specific output file
writechoice docusaurus nav ./my-site/sidebars.js -o navigation.json

# Specify docs folder explicitly
writechoice docusaurus nav ./my-site/sidebars.js --docs-dir ./my-site/docs --prefix mintlify

Example Input → Output

sidebars.js:

module.exports = {
  tutorialSidebar: [
    'intro',
    {
      type: 'category',
      label: 'Tutorial',
      items: [
        'tutorial/basics',
        'tutorial/deploy',
      ],
    },
  ],
};

nav.json output (with --prefix mintlify):

{
  "anchors": [
    {
      "anchor": "Tutorial Sidebar",
      "pages": [
        "mintlify/intro",
        {
          "group": "Tutorial",
          "pages": [
            "mintlify/tutorial/basics",
            "mintlify/tutorial/deploy"
          ]
        }
      ]
    }
  ]
}

Multiple sidebars produce tabs instead of anchors:

{
  "tabs": [
    {
      "tab": "Docs",
      "pages": [...]
    },
    {
      "tab": "API",
      "pages": [...]
    }
  ]
}

Typical Workflow

# 1. Convert all files
writechoice docusaurus convert ./my-docusaurus-site

# 2. Rename files to match their frontmatter slug/id
writechoice docusaurus slugify ./mintlify

# 3. Generate Mintlify navigation
writechoice docusaurus nav ./my-docusaurus-site/sidebars.js --prefix mintlify

# 4. Inspect nav.json and merge into docs.json
cat nav.json

Notes

• The command loads sidebars.js using require(). If that fails (e.g. TypeScript or ESM syntax), it falls back to a text-based parser that handles common patterns.
• Sidebar key names are converted from camelCase/snake_case to Title Case for the anchor / tab label.
• link and html items are silently skipped — they have no Mintlify equivalent.