Skip to main content

Sidebar Configuration

By default, Docusaurus generates the sidebar automatically from your docs/ folder structure using sidebar_position frontmatter and _category_.json files. This works for most projects.

If you need precise control over ordering or labels, define the sidebar explicitly in docs.config.json.

Explicit sidebar​

{
    "$schema": "https://docs.trickfirerobotics.com/docs.config.schema.json",
    "name": "My Project",
    "description": "...",
    "sidebar": [
        { "label": "Getting Started", "slug": "getting-started" },
        {
            "label": "Guides",
            "items": [
                { "label": "Installation", "slug": "guides/installation" },
                { "label": "Configuration", "slug": "guides/configuration" }
            ]
        },
        {
            "label": "Reference",
            "collapsed": true,
            "items": [
                { "label": "API", "slug": "reference/api" },
                { "label": "FAQ", "slug": "reference/faq" }
            ]
        },
        { "label": "TrickFire GitHub", "link": "https://github.com/TrickfireRobotics" }
    ]
}

Item types​

Links to a page in your docs/ folder. Use slug — the path relative to docs/ without the .md extension.

{ "label": "Getting Started", "slug": "getting-started" }
{ "label": "API Reference",   "slug": "reference/api" }

Links to any URL. Use link instead of slug.

{ "label": "GitHub", "link": "https://github.com/TrickfireRobotics" }
{ "label": "Notion", "link": "https://notion.so/trickfire" }

Group (category)​

Nests items under a collapsible heading. Groups can be nested.

{
    "label": "Guides",
    "collapsed": false,
    "items": [
        { "label": "Page A", "slug": "guides/page-a" },
        { "label": "Page B", "slug": "guides/page-b" },
        {
            "label": "Sub-section",
            "items": [{ "label": "Page C", "slug": "guides/sub/page-c" }]
        }
    ]
}

collapsed: false keeps the group open by default. All groups are collapsible by the user regardless.

Autogenerated sidebar (default)​

When sidebar is not set in docs.config.json, Docusaurus scans docs/ and builds the sidebar automatically. Control it with:

sidebar_position in frontmatter — sort order within the folder:

---
title: First Page
sidebar_position: 1
---

_category_.json in a subdirectory — label and position for that folder:

{
    "label": "Reference",
    "position": 3,
    "collapsed": true
}

The autogenerated sidebar works well for straightforward structures. Use an explicit sidebar only when you need items in a non-alphabetical order that sidebar_position can't express, or to include external links.