category.json

Overview

The _category_.json file is a configuration file used to organize and define metadata for a category within a documentation or content management system. This file helps structure the navigation and presentation of grouped content items (such as guides, tutorials, or articles) under a specific category label.

Specifically, this file defines:

• The label for the category, which is used as the visible name in navigation menus.

• The position of the category relative to other categories, influencing the order in which it appears.

• A link object that specifies the type of link associated with the category and its descriptive text.

This type of file is often used in static site generators or documentation frameworks (e.g., Docusaurus) that support category-based navigation and autogenerated index pages.

Detailed Explanation of the JSON Structure

Properties

The link Object

• type: Specifies the type of link for the category. Common values include:

  • "generated-index": Automatically generates an index page listing all documents under this category.

  • "doc": Links to a specific documentation page.

  • "external": Links to an external URL.

• description: A short descriptive text for the link, often shown on the generated index page or as a tooltip.

Usage Example

Assuming this _category_.json file is placed inside a directory representing a documentation category, the documentation generator will:

• Display the category labeled "Developers" in the navigation sidebar.

• Position this category as the fourth item among other categories.

• Create an autogenerated index page for the category that includes the description "Guides for hardcore developers".

Example navigation sidebar snippet:

1. Introduction
2. Tutorials
3. References
4. Developers  <-- This category
5. API

Implementation Details

• This file is a simple JSON configuration with no executable code.

• Its main role is to provide metadata that drives the UI and navigation structure of the documentation site.

• The "generated-index" link type triggers the documentation system to create a landing page that lists all documents contained in the category folder, using the description as a summary.

• The numeric position helps maintain consistent ordering when multiple categories exist.

Interaction with Other Parts of the System

• The category.json file is typically located within a directory that contains related markdown or documentation files.

• The documentation framework reads this file during the build process to determine:

  • How to label the category in sidebars or menus.

  • The ordering of categories relative to each other.

  • Whether to generate an index page or link to a specific document.

• It works closely with sidebar configuration files and markdown documents to provide a coherent browsing experience.

• Changes to this file affect navigation and indexing but do not modify content documents directly.

Visual Diagram

flowchart TD
    A[_category_.json] --> B[label: "Developers"]
    A --> C[position: 4]
    A --> D[link]
    D --> E[type: "generated-index"]
    D --> F[description: "Guides for hardcore developers"]

Diagram Explanation:

• The file category.json contains three main properties: label, position, and link.

• The link property itself is composed of type and description.

• This structure governs how the category is represented and linked within the documentation system.

Summary

The _category_.json file is a metadata descriptor for a documentation category, enabling clear organization, navigation order, and index page generation. Its simple JSON format influences how categories appear and behave within the larger documentation or content system.