---
sidebar_position: 2
sidebar_label: "Sidebar Sections"
sidebar_custom_props:
  section: "Components"
  section_position: 2
---

import Tabs from "@theme/Tabs";
import TabItem from "@theme/TabItem";

# Dynamic Sidebar Sections

Group related documentation pages under visual separators in the sidebar without creating static category structures.

## Overview

The dynamic sidebar sections feature allows you to organize documentation by adding custom section separators that group related pages together. Pages are grouped based on a `section` property in their frontmatter, and sections appear with visual separators in the sidebar.

**Benefits:**
- Keep files in a flat structure (no nested folders required)
- Flexible grouping without static `_category_.json` files
- Multiple sections per documentation instance
- Visual separation for better navigation
- Maintains alphabetical or position-based ordering within sections

## Setup

The `sidebarSections.js` file is included by default in projects created with `create-sp-days`. Simply configure it in your Docusaurus config:

### Configure Docusaurus

Add the `sidebarItemsGenerator` option to your docs plugin configuration:

```typescript title="docusaurus.config.ts"
{
  plugins: [
    [
      "@docusaurus/plugin-content-docs",
      {
        id: "resources",
        path: "resources",
        routeBasePath: "resources",
        // highlight-next-line
        sidebarItemsGenerator: require('./sidebarSections'),
      },
    ],
  ],
}
```

## Usage

### Add Section to Pages

In the frontmatter of any documentation page, add the `sidebar_custom_props.section` field:

```mdx title="api-reference.mdx"
---
sidebar_label: "API Reference"
sidebar_custom_props:
  section: "Templates"
  section_position: 2
---

# API Reference Template

Your content here...
```

```mdx title="quick-start.mdx"
---
sidebar_label: "Quick Start"
sidebar_custom_props:
  section: "Getting Started"
  section_position: 1
---

# Quick Start Guide

Your content here...
```

The `section_position` field is optional and controls the order in which sections appear. Sections without a position will be sorted alphabetically after positioned sections.

### Add Section to Categories

You can also apply sections to entire directories (categories) using `_category_.yml` or `_category_.json` files:

<Tabs>
  <TabItem value="yaml" label="YAML" default>
    ```yaml title="docs/layouts/_category_.yml"
    position: 3
    label: "Layouts"
    customProps:
      section: "Components"
      section_position: 2
    ```
  </TabItem>
  <TabItem value="json" label="JSON">
    ```json title="docs/templates/_category_.json"
    {
      "position": 2,
      "label": "Templates",
      "customProps": {
        "section": "Reference",
        "section_position": 3
      }
    }
    ```
  </TabItem>
</Tabs>

This groups the entire category under the specified section, allowing you to organize both individual pages and directories together.

### Pages Without Sections

Pages without a `section` property will appear at the top of the sidebar in their natural order:

```mdx title="introduction.mdx"
---
sidebar_label: "Introduction"
sidebar_position: 1
---

# Introduction

This page appears before any sections.
```

## Example Sidebar Structure

With the following pages:

- `introduction.mdx` (no section, `sidebar_position: 1`)
- `best-practices.mdx` (no section, `sidebar_position: 2`)
- `quick-start.mdx` (`section: "Getting Started"`)
- `installation.mdx` (`section: "Getting Started"`)
- `api-reference.mdx` (`section: "Templates"`)
- `cheat-sheet.mdx` (`section: "Templates"`)

The sidebar will display as:

```
Introduction
Best Practices
───── Getting Started ─────
Quick Start
Installation
───── Templates ─────
API Reference
Cheat Sheet
```

## Multiple Sections

You can create as many sections as needed. Each unique `section` value creates a new separator:

```mdx
sidebar_custom_props:
  section: "Advanced Topics"
```

```mdx
sidebar_custom_props:
  section: "Reference"
```

```mdx
sidebar_custom_props:
  section: "Troubleshooting"
```

## Ordering

### Within Sections

Use `sidebar_position` to control the order of pages within a section:

```mdx
---
sidebar_label: "Basic Usage"
sidebar_position: 1
sidebar_custom_props:
  section: "Templates"
  section_position: 2
---
```

```mdx
---
sidebar_label: "Advanced Usage"
sidebar_position: 2
sidebar_custom_props:
  section: "Templates"
  section_position: 2
---
```

### Section Order

Use `section_position` to control the order in which sections appear:

- Sections with `section_position: 1` appear first
- Sections with `section_position: 2` appear second, etc.
- Sections without `section_position` are sorted alphabetically and appear last

**Important:** All pages within the same section must use the same `section_position` value (or all omit it). Mixing different `section_position` values within a section will throw a validation error.

```mdx title="✅ Correct - Same section_position for all pages in section"
# Page 1
sidebar_custom_props:
  section: "Templates"
  section_position: 2

# Page 2  
sidebar_custom_props:
  section: "Templates"
  section_position: 2
```

```mdx title="❌ Incorrect - Different section_position values"
# Page 1
sidebar_custom_props:
  section: "Templates"
  section_position: 2

# Page 2
sidebar_custom_props:
  section: "Templates"
  section_position: 3  # ❌ Error!
```

:::tip
You only need to add `section_position` to one page in each section - if omitted on other pages in the same section, they'll inherit the behavior. However, adding it to all pages makes the intent clearer.
:::

:::warning Limitations
- Use only **one** `section` value per page
- All pages in a section must have the same `section_position` (or none)
:::

## Styling Customization

The separator styling uses CSS custom properties for theming:

- `--ifm-color-emphasis-600` - Text color
- `--ifm-color-emphasis-300` - Border color

To customize the separator appearance, edit the inline styles in `sidebarSections.js`:

```javascript title="sidebarSections.js"
value: `<div style="margin: 1rem 0 0.5rem; padding: 0.25rem 0; font-size: 0.75rem; ...">${sectionName}</div>`,
```

You can also target the generated class names with CSS:

```css title="custom.css"
[class*="sidebar-section-"] {
  /* Custom styles for all section separators */
}

.sidebar-section-templates {
  /* Styles specific to "Templates" section */
}
```

Class names are auto-generated from section names: `"Templates"` → `sidebar-section-templates`, `"Getting Started"` → `sidebar-section-getting-started`.