Editing sidebar and table of contents

After you create a topic, two navigation layers apply:

• The left sidebar, or the left-hand navigation, lists docs and categories for the whole site.
• The On this page list with links to headings within the current doc.

Both are configured in separate files: sidebars.js and docusaurus.config.js, respectively.

Adding a topic to the sidebar

Docusaurus sidebar setup

This article walks you through the 3di default setup for the sidebar. For the customisation options beyond these defaults and detailed reference, see the Docusaurus docs listed below.

Docusaurus sidebar reference

• Sidebar items reference
• Autogenerated sidebar items
• Using multiple sidebars

This template uses a manual sidebar defined in sidebars.js.
To add a new .mdx file under docs/ to the nav, you need to enter its doc ID to sidebars.js.

Folders alone do not appear in the sidebar

On this template, adding a folder under docs/ (even with _category_.json) does not add it to the left navigation. You must list the docs — or an autogenerated category — in sidebars.js.

For more information, see Folders and file system sidebars

The doc ID is the path under docs/ without the extension:

docs/template-description/my-topic/intro.mdx → template-description/my-topic/intro

sidebars.js

const sidebars = {
  tutorialSidebar: [
    {
      type: 'category',
      label: 'Using the 3di Docusaurus template',
      items: [
        'template-description/getting-started',
        {
          type: 'category',
          label: 'Creating content',
          items: [
            'template-description/create-content/creating-topics',
            'template-description/my-topic/intro',
          ],
        },
      ],
    },
  ],
};

export default sidebars;

Save sidebars.js and restart the dev server if the new entry doesn't appear immediately.

Categories

Group related docs under a category. A category always expands and collapses in the sidebar. What differs is whether clicking the category label also opens a landing page.

Template default

This template uses collapsible categories with no link – the label only expands or collapses the group. See Creating content and Creating content elements in sidebars.js for live examples.

Collapsible category (no landing page)

Clicking the label toggles the child items, but it doesn't navigate to a page.

sidebars.js

{
  type: 'category',
  label: 'My topic',
  items: [
    'template-description/my-topic/intro',
    'template-description/my-topic/setup',
  ],
},

Option	Effect
No link property	Collapsible group only (template default)
collapsed: true	Children hidden until the reader expands the category (default)
collapsed: false	Children visible when the sidebar loads
collapsible: false	Group always open; label is not a toggle

Category with an autogenerated landing page

Add link: { type: 'generated-index', … } when you want the category label to open a generated index that lists the child docs (with an optional description).

sidebars.js

{
  type: 'category',
  label: 'My topic',
  link: {
    type: 'generated-index',
    title: 'My topic',
    description: 'Overview of setup and configuration topics.',
  },
  items: [
    'template-description/my-topic/intro',
    'template-description/my-topic/setup',
  ],
},

With a generated index:

• Expanding still works via the chevron (or equivalent control).
• Clicking the label opens the generated landing page at a URL under that category.

Use this when the group needs an overview page. Prefer the template default (no link) when the first child topic is enough as an entry point.

Folders and file system sidebars

Docusaurus offers a second approach: build the sidebar from the folder tree (type: 'autogenerated'). In that mode, folder layout, _category_.json, and front matter such as sidebar_position / sidebar_label drive what appears in the nav.

This template doesn't use that for the main nav. The left sidebar is defined manually in sidebars.js. A new folder on disk stays invisible in the nav until you add entries there.

You can still mix approaches in one sidebar — for example one category whose items use type: 'autogenerated' and a dirName pointing at a folder — but that is opt-in in sidebars.js, not automatic.

For how filesystem sidebars and category folders work in full, see the Docusaurus docs:

• Create a doc (IDs, URLs, folder structure)
• Autogenerated sidebar items

On-page table of contents

The On this page list is built from headings in the current doc. On this template it shows ## H2 headings only, configured in docusaurus.config.js:

docusaurus.config.js

themeConfig: {
  tableOfContents: {
    minHeadingLevel: 2,
    maxHeadingLevel: 2,
  },
},

Use ## for major sections you want in that list. ### and deeper headings still render in the article but do not appear in On this page.

Hide the TOC on one page

Set front matter on the doc:

docs/my-topic/landing.mdx

---
title: Landing
hide_table_of_contents: true
---

Heading anchors

Headings get automatic ids for in-page links. For a custom id, append a comment after the heading.
For more information, see Basic text elements.