no-duplicate-sidebar-doc-ids
Disallow assigning the same Docusaurus doc id to multiple sidebar doc items in one sidebars file.
Targeted pattern scopeโ
This rule focuses on sidebars.* files and sidebar doc items that use either:
- doc shorthand strings such as
"introduction" - explicit doc items such as
{ type: "doc", id: "introduction" }
What this rule reportsโ
This rule reports repeated doc ids after their first appearance in the same sidebars file.
It does not report non-sidebar arrays such as metadata arrays or arbitrary string lists.
Why this rule existsโ
Docusaurus recommends using ref when the same doc needs to appear in multiple sidebars, rather than assigning that doc to multiple sidebars as a doc item.
Repeated doc assignments are risky because:
- implicit sidebar association becomes ambiguous
- navigation behavior is harder to reason about
- the config drifts away from Docusaurus guidance
โ Incorrectโ
const sidebars = {
docs: ["introduction", "introduction"],
};
โ Correctโ
const sidebars = {
docs: [
"introduction",
{ type: "ref", id: "introduction" },
],
};
Behavior and migration notesโ
This rule reports duplicates and provides suggestions, not an autofix.
The suggestion converts the repeated occurrence to ref, which matches Docusaurus guidance but still changes navigation semantics enough that it should remain reviewer-visible.
Additional examplesโ
โ Incorrect โ repeated explicit doc itemโ
const sidebars = {
docs: [
{ type: "doc", id: "introduction" },
{ type: "doc", id: "introduction" },
],
};
โ Correct โ repeated doc becomes refโ
const sidebars = {
docs: [
{ type: "doc", id: "introduction" },
{ type: "ref", id: "introduction" },
],
};
ESLint flat config exampleโ
import docusaurus2 from "eslint-plugin-docusaurus-2";
export default [docusaurus2.configs.strict];
When not to use itโ
Do not use this rule if your project intentionally tolerates repeated doc assignments and you do not want linting to push those repeated occurrences toward ref.
Rule catalog ID: R013