Skip to main content

Create New Documentation Group

You can organize your documentation into groups or categories. Each group will show as a section in the sidebar. This guide shows how to create a new documentation group category.

Think of it like folders on your computer. Instead of having one long list of files, you split them into folders so they are easier to find. In Docusaurus, these folders become collapsible sections in the sidebar.

Step 1: Create a New Folder in Docs​

  1. Open your project folder in VS Code
  2. Go to the docs/ folder - This is where all your documentation lives
  3. Create a new folder inside docs/ and name it with your category slug. Use lowercase and dashes.

Examples:

  • getting-started
  • installation-guide
  • api-reference
  • my-features

Good:

docs/getting-started/
docs/api-reference/

Bad (do not use spaces or uppercase):

docs/Getting Started/
docs/API Reference/

For this example, we will create docs/getting-started/

Step 2: Create the _category_.json File​

Inside your new folder, create a file named exactly:

_category_.json

Note: The file name must start with an underscore: _category_.json, not category.json

This file tells Docusaurus how to display the folder in the sidebar.

Step 3: Set Up Category Configuration​

Open _category_.json with VS Code and paste this template:

{
  "label": "Your Category Title",
  "position": 2,
  "link": {
    "type": "generated-index",
    "title": "Your Category - Full SEO Title",
    "description": "Write description about your docs group category here for SEO and category landing page"
  }
}

Field Explanation:

  • label: The name shown in the sidebar. Example: Getting Started
  • position: Order number in the sidebar. Smaller number = higher position. 1 = first, 2 = second, etc.
  • type: Keep it as generated-index - This auto-generates a category index page listing all docs inside
  • title: SEO title for the category landing page (browser tab)
  • description: SEO description for the category page (shows on the landing page and Google)

Real Implementation Example​

Let's create a "Getting Started" category:

File: docs/getting-started/_category_.json

{
  "label": "Getting Started",
  "position": 2,
  "link": {
    "type": "generated-index",
    "title": "Getting Started - Docusar Installation & Setup",
    "description": "Learn how to install, setup, and run the Docusar Docusaurus Themes project from scratch - complete guide for beginners"
  }
}

Result:

  • The sidebar will show Getting Started as the second item
  • Clicking it opens a landing page listing all docs inside the getting-started/ folder
  • The title and description will show on that landing page

Step 4: Add Docs Inside the Group​

Now you can create markdown files inside this folder:

docs/getting-started/
├── _category_.json
├── download.md
├── installation.md
├── create-project.md
└── run-locally.md

Each .md file will automatically appear inside this group in the sidebar, sorted by their sidebar_position in the frontmatter.

Step 5: Create More Groups​

To add another group, repeat the same steps.

Example - create docs/api-reference/_category_.json:

{
  "label": "API Reference",
  "position": 5,
  "link": {
    "type": "generated-index",
    "title": "API Reference - Complete Documentation",
    "description": "Complete API reference documentation for Docusar theme components and features"
  }
}

Tips:

  • Set position carefully: 1 for the most important, 10 for the last
  • Do not duplicate positions if possible, but if you do, Docusaurus will sort alphabetically
  • You can nest groups: docs/getting-started/installation/_category_.json works too

Now run npm run start and check the sidebar - your new group should appear.