category.json

Overview

The _category_.json file is a configuration file used primarily in documentation or knowledge base systems that support category grouping and navigation. Its main purpose is to define metadata for a documentation category, including a label, position within a navigation order, and a link configuration to control how the category index page is generated and described.

This file enables better organization and user navigation by grouping related documents under a common category with a clear label and order, and by linking to an automatically generated index page with a helpful description.

File Structure and Properties

The file contains a single JSON object with the following key properties:

label

• Type: string

• Purpose: Sets the human-readable name for the category.

• Example: "Best practices"

position

• Type: number

• Purpose: Determines the placement of this category relative to others when rendered in a menu or sidebar. Categories with smaller position values appear before those with larger ones.

• Example: 11

link

• Type: object

• Properties:

  • type: Describes the link type. Here, "generated-index" indicates a link to an automatically generated category index page.

  • description: A brief description displayed on the generated index page to inform users about the category's content.

• Example:

"link": {
  "type": "generated-index",
  "description": "Best practices on configuring a knowledge base."
}

This setup instructs the documentation system to create an index page summarizing the category contents, with the given description to guide readers.

Usage Example

In a documentation project, place _category_.json files inside folders representing categories. For example:

docs/
└── best-practices/
    ├── _category_.json
    ├── article1.md
    └── article2.md

The _category_.json might contain:

{
  "label": "Best practices",
  "position": 11,
  "link": {
    "type": "generated-index",
    "description": "Best practices on configuring a knowledge base."
  }
}

This will:

• Label the "best-practices" folder as "Best practices" in navigation.

• Position it at order 11 relative to other categories.

• Generate an index page describing "Best practices on configuring a knowledge base."

Implementation Details and Interaction

• This file is typically consumed by static site generators or documentation frameworks (e.g., Docusaurus).

• The generator reads the category.json to understand how to group and display the folder's contents.

• The "generated-index" link type triggers the system to build a category landing page summarizing all documents in this category.

• The position value affects the sidebar or menu ordering globally.

• The description in link is rendered on the generated index page to provide context.

Interaction with Other Parts of the System

• Works alongside Markdown or MDX files within the same folder to form a cohesive category.

• Sidebar or navigation components use this file for label and ordering.

• The generated index page enhances user navigation by summarizing category contents.

• Other categories with their own category.json files together define the full documentation hierarchy.

Mermaid Diagram

The following flowchart illustrates the structure and role of the _category_.json file within the documentation system:

flowchart TD
    A[_category_.json] --> B[label: "Best practices"]
    A --> C[position: 11]
    A --> D[link: generated-index]
    D --> E[description: "Best practices on configuring a knowledge base."]
    A -.-> F[Category Folder (best-practices)]
    F --> G[Documentation Files (article1.md, article2.md, ...)]
    A --> H[Navigation System]
    H --> I[Sidebar Ordering & Labels]
    H --> J[Generated Category Index Page]

Summary

The _category_.json file is a simple yet powerful configuration artifact that defines category labels, ordering, and index page metadata to organize and enhance navigation within documentation projects. It allows documentation frameworks to automatically generate navigable category pages with meaningful descriptions, improving the overall user experience.