Getting Started

Install the plugin and TypeScript:

npm install --save-dev eslint-plugin-docusaurus-2 typescript

Enable one preset in your flat config:

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

export default [docusaurus2.configs.recommended];

If you also want docs-content rules, add the opt-in content config separately:

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

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

What the presets provide today

Every preset already gives you a stable plugin contract:

• files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"]
• @typescript-eslint/parser
• ecmaVersion: "latest"
• sourceType: "module"
• plugin registration under "docusaurus-2"

The plugin also exposes three non-preset configs:

• docusaurus2.configs.content for *.md and *.mdx
• docusaurus2.configs.i18n for both JSX translation rules
• docusaurus2.configs["strict-mdx-upgrade"] for *.mdx only

The content configs use the plugin's text-content parser by default. Their rules also support the markdown/commonmark and markdown/gfm languages from @eslint/markdown, including when a later flat-config entry selects one of those languages. The i18n config uses the normal TypeScript parser and can be composed with recommended when both translation rules are wanted without the full strict preset.

strict-mdx-upgrade is intentionally scoped to the Docusaurus 3.10 MDX syntax migration rules only. The earlier 3.8 and 3.9 release-upgrade rules stay in the normal config-level preset ladder.

strict-mdx-upgrade is intentionally scoped to the 3.10 MDX syntax migration rules only. The 3.8 and 3.9 upgrade rules remain normal config-level rules in the regular preset ladder.

Instead of hand-maintaining a long rule inventory here, use these source-of-truth surfaces:

• Preset matrix for rules that belong to the preset ladder
• Config Surfaces for opt-in configs and direct rule opt-ins

At a high level, the current rule catalog covers these families:

• config, themeConfig, navbar, footer, and head-tag validation
• search, analytics, and DocSearch / Algolia integration hygiene
• sidebar, i18n, and navigation integrity
• theme package ownership and classic-theme stylesheet checks
• PWA, faster, and release-upgrade migration rules
• opt-in Markdown / MDX migration and content-aware rules
• owned Docusaurus link, heading, and translation API rules

Choosing a preset

• Start with recommended if you want the default future upgrade path and the stable config/sidebar rules.
• Start with config if you want only Docusaurus config, themeConfig, navbar/footer, and plugin-setup enforcement.
• Start with minimal if you want the smallest baseline.
• Use strict, all, or experimental when you also want the stricter Docusaurus page-module and site-source CSS checks.

Manual scoped setup

If you prefer to spread a preset into your own file-scoped config object, you can do that too:

import tsParser from "@typescript-eslint/parser";
import docusaurus2 from "eslint-plugin-docusaurus-2";

export default [
 {
  files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
  languageOptions: {
   parser: tsParser,
   parserOptions: {
    ecmaVersion: "latest",
    sourceType: "module",
   },
  },
  plugins: {
   "docusaurus-2": docusaurus2,
  },
  rules: {
   ...docusaurus2.configs.recommended.rules,
  },
 },
];

Important expectation

The plugin still has a deliberately focused rule catalog.

That means you can adopt the public runtime and start with a focused Docusaurus-specific baseline instead of inheriting a large bundle of speculative rules.

For stronger TypeDoc-only linting, pair this plugin with eslint-plugin-typedoc instead of expecting every TypeDoc concern to live here.

Where to go next

• Read the Overview for the product direction.
• Compare presets in the Preset index.