Skip to main content

​
Auto Sidebar Plugin

The auto sidebar plugin scans your documentation directory and automatically generates navigation and sidebar configuration based on the file structure and _meta.json files.

​
How It Works

The plugin:
  1. Scans the documentation directory recursively
  2. Finds _meta.json files that define navigation structure
  3. Generates nav and sidebar configuration automatically
  4. Supports multi-language and multi-version documentation

​
Configuration

The plugin is automatically enabled. You can customize it in doom.config.ts: 
import { defineConfig } from '@alauda/doom'
import { autoSidebarPlugin } from '@alauda/doom/plugins'

export default defineConfig({
  plugins: [
    autoSidebarPlugin({
      ignore: true,      // Respect onlyIncludeRoutes/internalRoutes
      export: true,      // Enable for export mode
      collapsed: false   // Default collapsed state for folders
    })
  ]
})

​
Meta Files

Place _meta.json in your root docs directory for top-level navigation:
docs/_meta.json
[
  {
    "text": "Guide",
    "link": "/guide",
    "position": "left"
  },
  {
    "text": "API Reference",
    "link": "/api"
  }
]
Place _meta.json in subdirectories to define sidebar structure:
docs/guide/_meta.json
[
  "introduction",
  "getting-started",
  {
    "type": "directory",
    "name": "advanced",
    "label": "Advanced Topics",
    "collapsible": true,
    "collapsed": false
  }
]

​
Meta File Format

Simple Link: 
{
  "text": "Guide",
  "link": "/guide",
  "activeMatch": "^/guide/",
  "position": "left" | "right"
}
With Children: 
{
  "text": "Resources",
  "items": [
    { "text": "Blog", "link": "/blog" },
    { "text": "Docs", "link": "/docs" }
  ]
}
String (simple): 
"getting-started"  // Resolves to getting-started.md(x)
File Object: 
{
  "type": "file",
  "name": "installation",
  "label": "Installation Guide"  // Override title from file
}
Directory Object: 
{
  "type": "directory",
  "name": "advanced",
  "label": "Advanced Topics",
  "collapsible": true,
  "collapsed": false
}

​
Directory Structure Example

docs/
├── _meta.json
├── guide/
│   ├── _meta.json
│   ├── home.md
│   └── advanced/
│       ├── _meta.json
│       └── plugin.md
└── api/
    ├── _meta.json
    └── reference.md

​
Root _meta.json

docs/_meta.json
[
  {
    "text": "Guide",
    "link": "/guide"
  }
]

​
Guide _meta.json

docs/guide/_meta.json
[
  "home",
  {
    "type": "directory",
    "name": "advanced",
    "label": "Advanced",
    "collapsible": true,
    "collapsed": false
  }
]

​
Advanced _meta.json

docs/guide/advanced/_meta.json
[
  {
    "type": "file",
    "name": "plugin",
    "label": "Plugin Development"
  }
]

​
Generated Config

Navigation: 
[
  {
    "text": "Guide",
    "link": "/guide"
  }
]
Sidebar: 
[
  {
    "text": "Home",
    "link": "/guide/home"
  },
  {
    "text": "Advanced",
    "collapsible": true,
    "collapsed": false,
    "items": [
      {
        "text": "Plugin Development",
        "link": "/guide/advanced/plugin"
      }
    ]
  }
]

​
Multi-Language Support

The plugin automatically handles multi-language documentation: 
docs/
├── en/
│   ├── _meta.json
│   └── guide/
│       └── ...
└── zh/
    ├── _meta.json
    └── guide/
        └── ...
Configure locales in your config: 
export default defineConfig({
  themeConfig: {
    locales: [
      { lang: 'en', label: 'English' },
      { lang: 'zh', label: '简体中文' }
    ]
  }
})

​
Multi-Version Support

The plugin supports versioned documentation: 
docs/
├── v1.0/
│   └── ...
└── v2.0/
    └── ...
Configure versions: 
export default defineConfig({
  multiVersion: {
    default: 'v2.0',
    versions: ['v1.0', 'v2.0']
  }
})

​
Plugin Options

export interface AutoSidebarPluginOptions {
  ignore?: boolean   // Respect onlyIncludeRoutes/internalRoutes
  export?: boolean   // Enable export mode
  collapsed?: boolean // Default collapsed state
}

​
Title Extraction

If no label is specified, the plugin extracts titles from:
  1. The title in frontmatter
  2. The first # Heading in the markdown
  3. The filename as fallback

​
Best Practices

  1. Use Consistent Naming - Use kebab-case for file and directory names
  2. Add Labels - Provide custom labels for better readability
  3. Organize Logically - Group related content in directories
  4. Order Matters - Items in _meta.json define the display order
  5. Test Navigation - Verify links work before deploying

Build docs developers (and LLMs) love

Get started for freeTalk to us