eslint-plugin-docusaurus-2

v2.0.4

Published

5 days ago

ESLint plugin for Docusaurus sites, docs repositories, and TypeDoc-integrated documentation workflows.

0High
0Medium
0Low

typpi

eslint eslint-plugin eslintplugin docusaurus documentation typedoc typescript

eslint-plugin-docusaurus-2

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
JSX translation, framework link/heading usage, Markdown/MDX hygiene, and Docusaurus 3.10 strict-MDX migration
and more to come!

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.x and 10.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-2 plugin 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 three opt-in 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.i18n | JS/TS/JSX/TSX | Enable both Docusaurus translation rules. | | 🧭 docusaurus2.configs["strict-mdx-upgrade"] | *.mdx | Enable the Docusaurus 3.10 strict-MDX syntax migration rules only. |

Additional opt-in configs

These are not part of the six preset tiers above.

Use them when you want focused translation or 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];

Enable both translation rules without adopting the full strict preset:

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

export default [docusaurus2.configs.recommended, docusaurus2.configs.i18n];

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/parser
ecmaVersion: "latest"
sourceType: "module"
plugin registration under "docusaurus-2"

These opt-in content configs use the plugin's text-content parser instead of @typescript-eslint/parser:

docusaurus2.configs.content
docusaurus2.configs["strict-mdx-upgrade"]

The i18n config uses the normal TypeScript parser because it inspects JSX translation components and calls.

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.

Fix legend:
- 🔧 = autofixable
- 💡 = suggestions available
- — = report only
Rules shown with no preset membership are rendered in the opt-in rules table below.
Preset key legend:

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

eslint-plugin-docusaurus-2

Table of contents

Installation

Compatibility

Quick start

Presets

Additional opt-in configs

Parser setup behavior

Plugin settings

Rules