Skip to main content

require-sidebar-category-items

Require items for explicit Docusaurus sidebar category objects.

Targeted pattern scope​

This rule focuses on sidebars.* files and specifically on explicit longhand category objects that declare:

  • type: "category"

It expects those objects to also declare:

  • items

What this rule reports​

This rule reports explicit sidebar category objects that omit the items field.

Why this rule exists​

Docusaurus category items are containers for other sidebar items.

When an explicit category object omits items, the object no longer matches the documented category shape and readers have to guess whether the config is incomplete or malformed.

This rule keeps longhand category objects aligned with the documented sidebar schema.

❌ Incorrect​

export default {
    docs: [
        {
            type: "category",
            label: "Guides",
        },
    ],
};

βœ… Correct​

export default {
    docs: [
        {
            type: "category",
            label: "Guides",
            items: ["introduction"],
        },
    ],
};

Behavior and migration notes​

This rule reports only. It does not autofix.

If a category should exist, the maintainer still has to decide which child items belong in it.

Additional examples​

βœ… Correct β€” shorthand categories already define their items implicitly​

export default {
    docs: [
        {
            Guides: ["introduction"],
        },
    ],
};

βœ… Correct β€” an empty items array is outside this rule’s scope​

export default {
    docs: [
        {
            type: "category",
            label: "Guides",
            items: [],
        },
    ],
};

ESLint flat config example​

import docusaurus2 from "eslint-plugin-docusaurus-2";

export default [docusaurus2.configs.recommended];

When not to use it​

Do not use this rule if your project intentionally permits explicit category placeholders without items and you do not want linting to enforce the documented Docusaurus category schema.

Rule catalog ID: R027

Further reading​