Skip to main content

docs-category-path

position: 3​

The _category_.json file attributes | Default path | Custom path

The _category_.json file in Docusaurus is used to define metadata for categories within the documentation. Here are the attributes that you can use in a _category_.json file:

  1. label: A string that sets the display name of the category in the sidebar.
  2. position: A number that defines the order of the category relative to other categories and documents at the same level.
  3. collapsed: A boolean that determines if the category should be collapsed by default in the sidebar.
  4. collapsible: A boolean that indicates whether the category can be collapsed in the sidebar.
  5. link: An object that defines a link for the category. It can be used to make the category itself a clickable link that navigates to a specific document or URL.
  • type: A string that specifies the type of link. It can be either 'doc' or 'generated-index'.
    • 'doc': Links the category to a specific document.
    • 'generated-index': Automatically generates an index page for the category.
  • id: (required if type is 'doc') The document ID that the category should link to.
  • title: (optional for type 'generated-index') The title of the generated index page.
  • description: (optional for type 'generated-index') The description of the generated index page.
  • slug: (optional for type 'generated-index') The URL slug for the generated index page.
  • keywords: (optional for type 'generated-index') An array of keywords for the generated index page.
  • image: (optional for type 'generated-index') The image URL for the generated index page.

Example _category_.json File​

Here’s an example of a _category_.json file with all possible attributes:

{
  "label": "Tutorials",
  "position": 1,
  "collapsed": true,
  "collapsible": true,
  "link": {
    "type": "generated-index",
    "title": "Tutorial Index",
    "description": "Index of all tutorials",
    "slug": "/tutorials",
    "keywords": ["tutorials", "index"],
    "image": "/img/tutorials.png"
  }
}

Explanation of Attributes​

  • label: Sets the name of the category as it appears in the sidebar.
  • position: Determines the order of the category in the sidebar. Lower numbers appear first.
  • collapsed: If true, the category is collapsed by default in the sidebar.
  • collapsible: If true, the category can be expanded or collapsed by the user.
  • link: Makes the category itself a link.
    • If type is 'doc', the category links to the specified document.
    • If type is 'generated-index', an index page is automatically generated for the category with the specified title, description, slug, keywords, and image.

By using these attributes, you can fully customize the behavior and appearance of categories in your Docusaurus sidebar.

Custom path​

Sure! Here’s an example of how to use the id attribute in a _category_.json file when the type is set to 'doc'. This will make the category itself a clickable link that navigates to a specific document.

Example Directory Structure​

Assume you have the following directory structure for your Docusaurus project:

docs
├── introduction.md
├── tutorials
│   ├── _category_.json
│   ├── tutorial1.md
│   └── tutorial2.md
└── reference
    ├── _category_.json
    └── api.md

Example _category_.json File​

docs/tutorials/_category_.json:

{
  "label": "Tutorials",
  "position": 1,
  "collapsed": true,
  "collapsible": true,
  "link": {
    "type": "doc",
    "id": "introduction"
  }
}

Explanation​

  • label: The name of the category as it appears in the sidebar, in this case, "Tutorials".
  • position: The order in which the category appears relative to other categories or documents.
  • collapsed: If true, the category is collapsed by default.
  • collapsible: If true, the category can be expanded or collapsed.
  • link: Makes the category itself a clickable link.
    • type: Set to 'doc' to indicate that the category should link to a specific document.
    • id: The document ID that the category should link to. In this case, it links to the document with the ID "introduction".

Document ID​

The id corresponds to the document ID, which is typically the filename without the .md extension and relative to the docs directory. In this example, introduction.md would have the ID "introduction".

So, when a user clicks on the "Tutorials" category in the sidebar, they will be taken to the introduction.md document.

Full Example of _category_.json​

To summarize, here’s the full content of the _category_.json file:

{
  "label": "Tutorials",
  "position": 1,
  "collapsed": true,
  "collapsible": true,
  "link": {
    "type": "doc",
    "id": "introduction"
  }
}

This setup helps to create a nested sidebar where clicking on the "Tutorials" category will navigate directly to the "Introduction" document, enhancing the user experience by providing quick access to key documents.