Skip to main content

Add New Category

This page shows you how to add a new category to Nocturne's sidebar.

Important: Decap CMS cannot create categories. You must do this manually in code.

Estimated time: 3 minutes.

What Is a Category?​

A category is a group of docs in the sidebar. Examples in Nocturne:

  • Getting Started
  • Configuration
  • Customization
  • Developer Guide

Each category maps to a folder in docs/.

The 3 Steps​

  1. Create the folder in docs/
  2. Create _category_.json inside the folder
  3. Add the category to sidebars.ts

Step 1 — Create the Folder​

In docs/, create a new folder:

mkdir docs/tutorials

Folder name: Use lowercase with hyphens. Example: tutorials, api-reference, advanced-guides.

Step 2 — Create _category_.json​

Inside the new folder, create _category_.json:

File: docs/tutorials/_category_.json

{
  "label": "Tutorials",
  "position": 5,
  "collapsed": false,
  "link": {
    "type": "generated-index",
    "title": "Tutorials",
    "description": "Step-by-step tutorials for Nocturne."
  }
}
FieldPurpose
labelCategory name in the sidebar
positionOrder (1, 2, 3...)
collapsedfalse = open, true = closed
link.typegenerated-index or doc
link.titleTitle for generated index page
link.descriptionDescription for generated index

Note: If you use a manual sidebars.ts, position is ignored — the order in sidebars.ts wins.

Step 3 — Add to sidebars.ts​

Open sidebars.ts and add the new category:

{
  type: 'category',
  label: 'Tutorials',
  collapsed: false,
  link: {
    type: 'doc',
    id: 'tutorials/index',
  },
  items: [
    'tutorials/index',
    'tutorials/first-tutorial',
    'tutorials/second-tutorial',
  ],
},

Add it in the position you want. Order matters.

Step 4 — Add the Index Page​

If you want an index page for the category, create:

File: docs/tutorials/index.md

---
sidebar_position: 1
sidebar_label: Overview
title: "Tutorials — Overview"
description: "Step-by-step tutorials for Nocturne."
---

# Tutorials

Intro text for this category.

## What You'll Learn

- Tutorial 1
- Tutorial 2

## What's Next?

👉 [Next: First Tutorial →](/docs/tutorials/first-tutorial)

Step 5 — Add the First Tutorial​

File: docs/tutorials/first-tutorial.md

---
sidebar_position: 2
sidebar_label: First Tutorial
title: "First Tutorial — Example"
description: "An example tutorial."
---

# First Tutorial

Content here.

Step 6 — Restart the Dev Server​

npm start

The new category appears in the sidebar.

Full Example​

Folder structure:

docs/
└── tutorials/
    ├── _category_.json
    ├── index.md
    ├── first-tutorial.md
    └── second-tutorial.md

docs/tutorials/_category_.json:

{
  "label": "Tutorials",
  "position": 5,
  "collapsed": false,
  "link": {
    "type": "doc",
    "id": "tutorials/index"
  }
}

sidebars.ts:

{
  type: 'category',
  label: 'Tutorials',
  collapsed: false,
  link: {
    type: 'doc',
    id: 'tutorials/index',
  },
  items: [
    'tutorials/index',
    'tutorials/first-tutorial',
    'tutorials/second-tutorial',
  ],
},

Two ways to link a category:

Type 1 — generated-index​

Auto-generates an index page listing all docs in the category.

{
  "link": {
    "type": "generated-index",
    "title": "Tutorials",
    "description": "Step-by-step tutorials."
  }
}

Pros: No need to write an index.md. Cons: Less control over the index page.

Type 2 — doc​

Links to a custom index.md.

{
  "link": {
    "type": "doc",
    "id": "tutorials/index"
  }
}

Pros: Full control over the index page. Cons: Need to write an index.md.

Nocturne uses doc for most categories — more control.

Adding Categories via Decap CMS​

Decap CMS cannot create categories. This is a known limitation.

Why: Decap CMS edits content, not config files. _category_.json and sidebars.ts are config.

Workaround: Add the category manually in code, then edit content via CMS.

See Decap CMS → Adding a New Category for details.

Troubleshooting​

Category doesn't appear​

  1. Check that _category_.json is inside the folder
  2. Check that the folder is in docs/
  3. Check that the category is added to sidebars.ts
  4. Restart the dev server

"These sidebar document ids do not exist"​

  1. Check the doc ID — must match file path without .md
  2. Check that all items in the category exist
  3. Check for typos

Category is not clickable​

Add a link field to the category in sidebars.ts.

Category appears in the wrong order​

The order in sidebars.ts wins. Move the category object to the right position.

New docs don't appear in the category​

  1. Check that they're in the items array
  2. Check that the doc IDs are correct
  3. Restart the dev server

Deleting a Category​

  1. Remove the category from sidebars.ts
  2. Delete the folder in docs/
  3. Restart the dev server

Warning: Docs inside the folder are deleted too. Move them elsewhere first if needed.

What's Next?​

You've completed the Developer Guide.