eslint-plugin-docusaurus-2
June 18, 2026 · View on GitHub
eslint-plugin-docusaurus-2 is an ESLint plugin for Docusaurus sites, docs repositories, and TypeDoc-integrated documentation workflows.
It ships focused Docusaurus-specific rules and Flat Config presets for teams that want stricter guarantees around:
docusaurus.config.*- theme config (
navbar,footer,metadata,colorMode, announcement bars) - classic-theme global stylesheet configuration
- search integrations (Algolia DocSearch and @easyops-cn/docusaurus-search-local)
- package ownership checks for configured themes and search providers
- analytics migrations and modern telemetry config
- sidebars and docs navigation
- pages, routing, and asset usage
- plugin-pwa and docs-site integration details
- Markdown and MDX content hygiene and Docusaurus 3.10 strict-MDX migration
- and more to come!
Table of contents
- Installation
- Compatibility
- Quick start
- Presets
- Additional opt-in content configs
- Parser setup behavior
- Plugin settings
- Rules
- Documentation
- Roadmap direction
- Contributing
- License
- Contributors ✨
Installation
npm install --save-dev eslint-plugin-docusaurus-2 typescript
eslint-plugin-docusaurus-2 is published for broad public use. Install it into a workspace that already owns its ESLint and TypeScript toolchain.
Compatibility
- ESLint:
9.xand10.x - Config system: Flat Config only
- Node.js:
>=22 - TypeScript:
>=5.9
Quick start
import docusaurus2 from "eslint-plugin-docusaurus-2";
export default [docusaurus2.configs.recommended];
That is enough for the plugin to provide:
- the
docusaurus-2plugin namespace - parser wiring through
@typescript-eslint/parser - a stable Flat Config preset surface
Presets
This plugin currently exports six public presets:
| Preset | Purpose |
|---|---|
🟢 docusaurus2.configs.minimal | Smallest future-ready baseline. |
🔵 docusaurus2.configs.config | Focused config/theme/plugin rule set. |
🟡 docusaurus2.configs.recommended | Default starting point for most repositories. |
🔴 docusaurus2.configs.strict | Stricter future tier for mature sites. |
🟣 docusaurus2.configs.all | Every stable rule once the catalog grows. |
🧪 docusaurus2.configs.experimental | Future experimental rule candidates. |
It also exports two opt-in content configs that are intentionally kept outside the preset ladder:
| Config | Scope | Purpose |
|---|---|---|
📝 docusaurus2.configs.content | *.md/*.mdx | Enable text/content-aware docs rules without touching JS/TS presets. |
🧭 docusaurus2.configs["strict-mdx-upgrade"] | *.mdx | Enable the Docusaurus 3.10 strict-MDX syntax migration rules only. |
Additional opt-in content configs
These are not part of the six preset tiers above.
Use them when you want docs-content linting in addition to the normal JS/TS config presets.
import docusaurus2 from "eslint-plugin-docusaurus-2";
export default [docusaurus2.configs.recommended, docusaurus2.configs.content];
If you only want the Docusaurus 3.10 strict-MDX migration rules, use the narrower config instead:
import docusaurus2 from "eslint-plugin-docusaurus-2";
export default [docusaurus2.configs["strict-mdx-upgrade"]];
Parser setup behavior
Every preset already includes:
files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"]@typescript-eslint/parserecmaVersion: "latest"sourceType: "module"- plugin registration under
"docusaurus-2"
The opt-in content configs use the plugin's text-content parser instead of @typescript-eslint/parser:
docusaurus2.configs.contentdocusaurus2.configs["strict-mdx-upgrade"]
Plugin settings
import docusaurus2 from "eslint-plugin-docusaurus-2";
export default [
{
...docusaurus2.configs.recommended,
settings: {
"docusaurus-2": {
// Suppress plugin autofixes globally while preserving reports.
// disableAllAutofixes: true,
},
},
},
];
When settings["docusaurus-2"].disableAllAutofixes is true, rules still report diagnostics and suggestions, but direct autofixes are suppressed.
For stronger TypeDoc-specific linting around API doc authoring and TypeDoc conventions, pair this plugin with eslint-plugin-typedoc.
Rules
The current rule catalog focuses on Docusaurus config, validation, sidebar, and site-source CSS correctness.
The public preset surface is stable, and the rule catalog is intentionally focused while higher-value Docusaurus rule gaps are explored.
Fixlegend:🔧= autofixable💡= suggestions available—= report only
- Rules shown with no preset membership are rendered in the opt-in rules table below.
Preset keylegend:
Opt-in rules
These rules are intentionally outside the six preset tiers. Some are available through opt-in content configs; others are direct rule opt-ins only.
Config surfacelegend:
Documentation
- Rules overview:
docs/rules/overview.md - Getting started:
docs/rules/getting-started.md - Preset reference:
docs/rules/presets/index.md - Docusaurus site app:
docs/docusaurus/
Roadmap direction
The next phase of the plugin is focused on expanding the Docusaurus rule catalog with more high-signal checks. Likely areas include:
- Docusaurus config and route metadata rules
- sidebar and docs-structure validation rules
- TypeDoc-generated API boundary rules
- site-contract and docs-build integration rules
Contributing
See CONTRIBUTING.md.
License
Contributors ✨
Thanks goes to these wonderful people (emoji key):
 Meta ️️️️♿️ 💬 🔊 📝 🐛 💼 💻 🖋 🔣 🎨 📖 📋 💡 💵 🔍 🤔 🚇 🚧 🧑🏫 📦 🔌 📆 📣 🔬 👀 🛡️ 📢 ⚠️ 🔧 🌍 ✅ 📓 📹 |
 Nick2bad4u 🐛 💻 📖 🤔 🚇 🚧 👀 ⚠️ 🔧 |
 Snyk bot 🛡️ 🚇 🚧 👀 |
 StepSecurity Bot 🛡️ 🚇 🚧 |
![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4?s=80) dependabot[bot] 🚇 🛡️ |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?v=4?s=80) github-actions[bot] 💻 🚇 |
This project follows the all-contributors specification. Contributions of any kind welcome!