Getting Started

June 18, 2026 ยท View on GitHub

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 two non-preset content configs:

  • docusaurus2.configs.content for *.md and *.mdx
  • docusaurus2.configs["strict-mdx-upgrade"] for *.mdx only

Those use the plugin's text-content parser so content migration and docs-content rules stay opt-in instead of being mixed into the normal JS/TS preset ladder.

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:

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

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