Skip to main content

config-surfaces

Understand the public rollout layers exposed by eslint-plugin-docusaurus-2.

Preset ladderโ€‹

The six presets are the default rollout ladder for JavaScript and TypeScript source files:

  • docusaurus2.configs.minimal
  • docusaurus2.configs.config
  • docusaurus2.configs.recommended
  • docusaurus2.configs.strict
  • docusaurus2.configs.all
  • docusaurus2.configs.experimental

Use these when you want Docusaurus config, theme, sidebar, routing, and package-ownership rules on the normal source-code surface.

Opt-in configsโ€‹

The plugin also exports focused configs outside the preset ladder.

๐ŸŒ docusaurus2.configs.i18nโ€‹

Use this JavaScript/TypeScript config to enable both owned Docusaurus translation rules:

  • no-untranslated-text
  • string-literal-i18n-messages

This is useful when recommended should retain its lower-noise translation policy but a specific site wants complete JSX translation enforcement.

๐Ÿ“ docusaurus2.configs.contentโ€‹

Use this when you want rules that inspect Markdown or MDX content directly.

The config uses the plugin's lightweight text parser by default. Its rules also support markdown/commonmark and markdown/gfm, so a later flat-config entry can select an @eslint/markdown language without disabling the Docusaurus content checks.

Current examples include:

  • MDX migration rules
  • Mermaid content and package checks

๐Ÿงญ docusaurus2.configs["strict-mdx-upgrade"]โ€‹

Use this narrower config when you only want the Docusaurus 3.10 strict-MDX migration rules for .mdx files.

The earlier 3.8 and 3.9 release-upgrade rules are config-level rules, so they stay in the normal preset ladder instead of this MDX-only config.

Direct rule opt-insโ€‹

Some rules are intentionally outside both the preset ladder and the content-config layer.

These are rules you enable one-by-one in your own config because they are advisory, noisy, or too situational for bundled rollout.

How to read the generated rule tablesโ€‹

  • The main preset matrix shows rules that belong to one or more of the six preset tiers.
  • The generated Opt-in rules table shows rules outside that preset ladder.
  • In that opt-in table:
    • a config surface such as docusaurus2.configs.i18n means the rule is available through an opt-in config
    • direct rule opt-in only means you enable the rule explicitly in rules

Exampleโ€‹

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

export default [
 docusaurus2.configs.recommended,
 docusaurus2.configs.i18n,
 docusaurus2.configs.content,
 {
  rules: {
   "docusaurus-2/local-search-will-not-work-in-dev": "warn",
  },
 },
];

Where to look nextโ€‹

  • Read Getting Started for rollout guidance.
  • Read Presets for the generated preset matrix and opt-in rules table.