Skip to main content

​
Auto Sidebar

The Auto Sidebar plugin automatically generates navigation and sidebar configuration based on your documentation directory structure and _meta.json files. This eliminates the need to manually maintain navigation config as your documentation grows.

​
Overview

The plugin scans your documentation directory and:
  • Extracts navigation configuration from root-level _meta.json files
  • Generates sidebar configuration from subdirectory _meta.json files
  • Automatically extracts page titles from frontmatter or H1 headings
  • Supports multiple languages and versions

​
Configuration

The Auto Sidebar plugin is enabled by default in Doom. You can configure its behavior in your doom.config.yml: 
sidebar:
  collapsed: false  # Whether sidebar groups are collapsed by default

​
Plugin Options

When used programmatically, the plugin accepts these options: 
interface AutoSidebarPluginOptions {
  ignore?: boolean      // Ignore internal routes
  export?: boolean      // Run in PDF export mode
  collapsed?: boolean   // Collapse sidebar groups by default
}

​
Directory Structure

Here’s an example documentation structure: 
docs/
├── _meta.json          # Root navigation config
├── guide/
│   ├── _meta.json      # Sidebar config for guide section
│   ├── getting-started.md
│   └── advanced/
│       ├── _meta.json
│       └── configuration.md
└── api/
    ├── _meta.json
    └── reference.md

​
Meta Configuration

​
Root Navigation (_meta.json)

The root _meta.json defines top-level navigation items: 
[
  {
    "text": "Guide",
    "link": "/guide",
    "position": "left"
  },
  {
    "text": "API",
    "items": [
      {
        "text": "Reference",
        "link": "/api/reference"
      }
    ]
  }
]
Sidebar _meta.json files define the structure within a section: 
[
  "getting-started",
  {
    "type": "dir",
    "name": "advanced",
    "label": "Advanced Topics",
    "collapsible": true,
    "collapsed": false
  }
]

​
Meta Item Types

​
String Format

Simple string references a file by name (extension optional): 
["getting-started", "configuration"]
The plugin will:
  • Find the file (tries .mdx, .md, .tsx, .jsx, .ts, .js extensions)
  • Extract the title from frontmatter or first H1 heading
  • Generate the appropriate link

​
Object Format

For more control, use the object format: 
{
  "type": "file",
  "name": "getting-started",
  "label": "Getting Started Guide"
}

​
Meta Item Properties

​
type
string
Item type: file, dir, divider, custom-link, or section-header
​
name
string
required
File or directory name (without extension for files)
​
label
string
Display text for the sidebar item. If omitted, extracted from page title.
​
link
string
Custom URL (for custom-link type)
​
collapsible
boolean
default:false
Whether the directory group can be collapsed
​
collapsed
boolean
default:false
Whether the directory group is collapsed by default
​
tag
string
Tag to display next to the item (e.g., “New”, “Beta”)
​
dashed
boolean
Use dashed line for dividers
​
overviewHeaders
number[]
Heading levels to include in overview (e.g., [2, 3])
​
context
string
Additional context for the item

​
Title Extraction

The plugin automatically extracts page titles from:
  1. Frontmatter title field (highest priority)
  2. First H1 heading in the content
  3. Filename as fallback

​
Example

---
title: My Custom Title
---

# This H1 is ignored when frontmatter title exists

Content here...

​
Multi-language Support

Auto Sidebar works seamlessly with multiple languages: 
docs/
├── en/
│   ├── _meta.json
│   └── guide/
│       ├── _meta.json
│       └── getting-started.md
└── zh/
    ├── _meta.json
    └── guide/
        ├── _meta.json
        └── getting-started.md
Configure languages in your config: 
lang: en
themeConfig:
  locales:
    - lang: en
      label: English
    - lang: zh
      label: 中文

​
Versioning Support

Auto Sidebar also supports versioned documentation: 
docs/
├── v1.0/
│   ├── _meta.json
│   └── guide/
└── v2.0/
    ├── _meta.json
    └── guide/
Configure versions: 
multiVersion:
  default: v2.0
  versions:
    - v1.0
    - v2.0

​
File Extensions

By default, the plugin looks for these extensions:
  • .mdx
  • .md
  • .tsx
  • .jsx
  • .ts
  • .js
You can customize this in your config: 
route:
  extensions:
    - .mdx
    - .md

​
Example Configuration

Here’s a complete example showing Auto Sidebar in action: 
[
  {
    "text": "Guide",
    "link": "/guide/getting-started"
  },
  {
    "text": "API",
    "link": "/api"
  }
]

​
Programmatic Usage

You can also use the Auto Sidebar plugin programmatically: 
import { autoSidebarPlugin } from '@alauda/doom'
import { defineConfig } from '@rspress/core'

export default defineConfig({
  plugins: [
    autoSidebarPlugin({
      collapsed: false,
      ignore: false,
      export: false
    })
  ]
})
The Auto Sidebar plugin replaces Rspress’s built-in auto-nav-sidebar plugin automatically.

​
Best Practices

Use Descriptive Names

Choose clear, descriptive file and directory names that make sense in URLs.

Organize Logically

Group related content together in directories with appropriate _meta.json files.

Set Frontmatter Titles

Always set explicit title fields in frontmatter for better control.

Keep Flat When Possible

Avoid deep nesting - aim for 2-3 levels maximum for better user experience.

​
Troubleshooting

​
File Not Found Warning

If you see warnings about missing files: 
Can't find the file: /path/to/file
Solution: Check that:
  • The file exists with one of the supported extensions
  • The filename in _meta.json matches exactly (case-sensitive)
  • The file is not in an excluded directory
If sidebar changes don’t appear: Solution:
  • Restart the dev server (it watches _meta.json files)
  • Check for syntax errors in your _meta.json files
  • Verify the directory structure matches your meta configuration

​
Missing Titles

If titles show as filenames: Solution:
  • Add a title field in the page’s frontmatter
  • Ensure the page has a first-level heading (# Title)
  • Use the label property in _meta.json to override

Build docs developers (and LLMs) love

Get started for freeTalk to us