category.json

Overview

The _category_.json file is a configuration file used primarily for organizing and categorizing content within a documentation or knowledge base system, such as those generated by tools like Docusaurus or similar static site generators. Its main purpose is to define metadata for a category or folder, including how it is labeled, ordered (positioned), and linked within the navigation structure.

This file does not contain executable code but rather descriptive data that influences how the documentation system presents and navigates grouped content. Specifically, it helps generate index pages and navigation menus that organize related documents under a named category.

File Structure and Fields

The file is structured as a JSON object with the following key properties:

Detailed Explanation of Fields

• label

  • Purpose: Names the category for display purposes.

  • Example: "MCP" — This label will appear in the sidebar or navigation as the category heading.

• position

  • Purpose: Determines the category's relative position in menus or lists. Categories with lower position values appear before those with higher values.

  • Example: 40 — This category will be placed after categories with position values less than 40.

• link

  • Purpose: Specifies the type of link the category generates and includes a description to provide context in the UI.

  • Fields inside link:

    • type (string): The kind of link to create.

      • "generated-index" means the system creates an index page that summarizes the category contents automatically.

    • description (string): Text describing the category's focus or purpose, often shown on the generated index page.

  • Example:

    "link": {
      "type": "generated-index",
      "description": "Guides and references on accessing RAGFlow's knowledge bases via MCP."
    }
    

    This means the category will have an auto-generated index page describing access to RAGFlow knowledge bases via MCP.

Usage Example

Suppose you have a documentation folder named MCP containing several markdown files about the MCP system. To create a nicely organized navigation category with a summary page, place this _category_.json file inside that folder:

/docs
  /MCP
    _category_.json
    intro.md
    usage.md
    reference.md

This configuration will produce a sidebar entry labeled MCP appearing at position 40 in the menu, linking to a generated index page that shows the description and lists the files contained.

Important Implementation Details

• The position value is crucial for ordering categories; it allows fine-grained control over navigation menus.

• The link.type field supports different types such as:

  • "doc": links directly to a specific document.

  • "generated-index": creates an index page summarizing the category.

• The description inside link enhances user experience by providing context on the generated index page.

• This file must be named exactly category.json to be recognized by the documentation system.

Interaction with Other Files and System Components

• Documentation Files: The category file groups related markdown or documentation files, influencing their presentation in the sidebar.

• Sidebar Configuration: The static site generator reads this file when building navigation structures, ensuring that categories appear with the specified label, order, and link behavior.

• Generated Index Pages: When link.type is "generated-index", the system dynamically generates an index page summarizing the category content using this metadata.

• Other category.json Files: The system aggregates multiple category.json files from different folders to build a hierarchical and ordered navigation tree.

Visual Diagram

This file defines a data structure rather than code classes or functions. A flowchart illustrating how the file's fields influence navigation generation is appropriate:

flowchart TD
    A[_category_.json file]
    A --> B[label: Category display name]
    A --> C[position: Category order]
    A --> D[link object]
    D --> D1[type: link type]
    D --> D2[description: summary text]
    
    B --> E[Displayed in Sidebar]
    C --> E
    D1 --> F{Link Type}
    F -->|generated-index| G[Generate Index Page]
    F -->|doc| H[Direct Document Link]
    G --> I[List category contents]
    I --> J[Show description]

Summary

The _category_.json file is a simple yet powerful configuration artifact used to organize documentation content into labeled categories with controlled positioning and linking behavior. It enables automated generation of index pages that improve navigation and user comprehension within a knowledge base or documentation site.