category.json

Overview

The _category_.json file serves as a configuration descriptor used primarily in documentation or content management systems that organize documents into navigable categories. This particular file defines metadata for a category or section, including its label (display name), position (ordering), and a link configuration that guides the user to a related generated index page.

In essence, this file helps structure and organize content hierarchically, providing user-friendly navigation labels and pointers to relevant overview or index pages within a documentation site or knowledge base.

File Structure and Fields

This file is a JSON object with the following key properties:

Property	Type	Description
`label`	string	The display name of the category or section. It appears in navigational menus or sidebars.
`position`	integer	The ordering index that determines the category’s position relative to siblings. Lower numbers typically appear first.
`link`	object	Defines the type and description of a related navigational link associated with this category.

`link` Object Details:

Property	Type	Description
`type`	string	Specifies the kind of link. In this case, `"generated-index"` implies an auto-generated index page for the category.
`description`	string	A short text describing the purpose or content of the linked page, e.g., "RAGFlow Quick Start".

Example Usage

This file is typically placed inside a folder that corresponds to a category in a documentation structure. Documentation platforms (such as Docusaurus) read this file to render sidebar navigation and category indexes.

{
  "label": "Get Started",
  "position": 1,
  "link": {
    "type": "generated-index",
    "description": "RAGFlow Quick Start"
  }
}

Here, the category is labeled "Get Started" and will appear first (position: 1) in the navigation order. The link property indicates that a generated index page exists, giving users a quick-start guide named "RAGFlow Quick Start".

Important Implementation Details

Ordering: The position field is crucial for controlling the order of categories in the navigation UI.
Generated Index: By specifying "type": "generated-index", the system automatically creates an overview page summarizing all documents under this category, eliminating the need for manual index pages.
Extensibility: Additional properties can be added in similar category.json files to customize navigation further, but this minimal set provides core functionality.

Interaction With Other Parts of the System

Documentation Generator: This JSON file is read by static site generators such as Docusaurus to build sidebar menus and category index pages.
Folder Structure: Each category.json file is placed inside a folder representing a documentation category. The file’s properties influence how the folder and its contained documents appear in the generated site.
Navigation UI: The label and position fields directly affect the sidebar or navigation menu labels and order.
Generated Index Page: The link of type generated-index triggers the creation of an automatic index page aggregating all documents in the category folder, linked with the provided description.

Visual Diagram

The following Mermaid diagram illustrates the structure of the _category_.json file and the relationships between its properties:

classDiagram
    class CategoryConfig {
        +label: string
        +position: int
        +link: Link
    }

    class Link {
        +type: string
        +description: string
    }

    CategoryConfig --> Link : contains

Summary

The _category_.json file is a lightweight yet powerful configuration file that organizes documentation content into categories with clear labels and ordering. It enables automatic generation of index pages and improves navigational clarity in documentation systems. Understanding and properly configuring this file ensures a well-structured and user-friendly documentation site.