stylelint-plugin-docusaurus

Stylelint plugin scaffold for Docusaurus-focused CSS rules, shareable configs, and future Docusaurus styling conventions.

Table of contents

• Installation
• Quick start
• Exports
• Configs
• Rules
• Docusaurus docs CSS guardrails
• Documentation
• Contributors ✨

Installation

npm install --save-dev stylelint stylelint-plugin-docusaurus

Compatibility

• Supported Stylelint versions: 16.x and 17.x
• Config system: ESM config files such as stylelint.config.mjs
• Node.js runtime: >=22.0.0

Quick start

Use the plugin-scoped recommended shareable config:

import { docusaurusPluginConfigs } from "stylelint-plugin-docusaurus";

export default docusaurusPluginConfigs["docusaurus-recommended"];

Or consume the config from extends (recommended when composing multiple presets):

export default {
 extends: [
  "stylelint-config-standard",
  "stylelint-config-recess-order",
  "stylelint-config-idiomatic-order",
  "stylelint-config-standard-scss",
  "stylelint-config-tailwindcss",
  "stylelint-plugin-docusaurus/configs/docusaurus-recommended",
 ],
};

If you prefer manual plugin registration, use the package name string (or the plugin-pack import form):

import docusaurusPlugin from "stylelint-plugin-docusaurus";

export default {
 plugins: ["stylelint-plugin-docusaurus"],
 // Alternative explicit pack form:
 // plugins: [...docusaurusPlugin],
 rules: {
  "docusaurus/no-mobile-navbar-backdrop-filter": true,
 },
};

Exports

The package currently exports:

• default Stylelint plugin pack (default)
• docusaurusPluginConfigs
• configNames, ruleNames, ruleIds, rules, and meta
• extends-ready subpath configs:
  • stylelint-plugin-docusaurus/configs/docusaurus-recommended
  • stylelint-plugin-docusaurus/configs/docusaurus-all
  • stylelint-plugin-docusaurus/configs/docusaurus-docs-safe

Configs

Config key	Purpose
docusaurusPluginConfigs["docusaurus-recommended"]	Default low-noise config for broadly applicable Docusaurus rules.
docusaurusPluginConfigs["docusaurus-all"]	Exhaustive stable config for every public docusaurus/* rule.
docusaurusPluginConfigs["docusaurus-docs-safe"]	Opinionated docs-surface preset for Docusaurus docs CSS workflows.

docusaurus-recommended enables the baseline rule set; docusaurus-all enables the full stable public catalog.

Rules

Fix legend:

• 🔧 = autofixable
• — = report only

Preset key legend:

• 🟢 — docusaurusPluginConfigs["docusaurus-recommended"]
• 🟣 — docusaurusPluginConfigs["docusaurus-all"]
• 🛡️ — docusaurusPluginConfigs["docusaurus-docs-safe"]

Rule	Fix	Preset key	Description
no-broad-all-resets-outside-isolation-subtrees	—	🟣	Disallow broad all: initial|revert|unset resets outside explicitly isolated local subtrees.
no-color-scheme-on-docusaurus-html-root	—	🟣	Disallow color-scheme declarations on Docusaurus root selectors managed by the framework.
no-direct-project-token-consumption-in-css-modules	—	🟣	Disallow direct project-scoped CSS custom property token consumption in CSS Modules declarations.
no-direct-theme-token-consumption-in-css-modules	—	🟣	Disallow direct --ifm-* and --docsearch-* token consumption in CSS Modules declarations.
no-docusaurus-layer-name-collisions	—	🟣	Disallow author-defined cascade layer names that collide with reserved Docusaurus-managed layer prefixes.
no-hardcoded-docusaurus-breakpoint-values	—	🟣	Disallow hardcoded pixel values in @media queries that match Docusaurus/Infima documented breakpoints.
no-important-on-infima-or-docusaurus-selector-overrides	—	🟣	Disallow !important on declarations inside rules that target Infima or Docusaurus class selectors.
no-invalid-theme-custom-property-scope	—	🟢 🛡️ 🟣	Disallow declaring Docusaurus theme custom properties outside global theme scopes, except for DocSearch variables scoped to the DocSearch UI.
no-mobile-navbar-backdrop-filter	—	🟢 🛡️ 🟣	Disallow backdrop-filter on Docusaurus navbar selectors unless it is guarded behind the desktop breakpoint.
no-mobile-navbar-stacking-context-traps	—	🟣	Disallow containing-block and stacking-context properties on Docusaurus navbar selectors unless they are guarded behind the desktop breakpoint.
no-navbar-breakpoint-desync	—	🟣	Disallow custom CSS breakpoints for Docusaurus mobile navbar/sidebar surfaces that can desync from the built-in JS breakpoint.
no-revert-layer-outside-isolation-subtrees	—	🟣	Disallow revert-layer usage outside explicitly isolated local subtrees.
no-subtree-data-theme-selectors	—	🟢 🛡️ 🟣	Disallow subtree-scoped data-theme selectors that do not start from the Docusaurus root color-mode attribute.
no-unanchored-infima-subcomponent-selectors	—	🟣	Disallow unanchored Infima subcomponent selectors in global Docusaurus stylesheets.
no-unsafe-theme-internal-selectors	—	🟣	Disallow curated unsafe Docusaurus internal selector fallbacks that have no documented stable CSS contract.
no-unscoped-content-element-overrides	—	🟣	Disallow unscoped content-element overrides that leak across the whole Docusaurus site.
no-unstable-docusaurus-generated-class-selectors	—	🟣	Disallow exact selectors that target Docusaurus theme CSS-module class names with unstable hash suffixes.
no-unwrapped-global-theme-selectors-in-css-modules	—	🟢 🛡️ 🟣	Disallow unwrapped Docusaurus and Infima global theme selectors inside CSS Modules.
prefer-data-theme-color-mode	🔧	🟢 🛡️ 🟣	Prefer Docusaurus data-theme selectors over legacy theme-dark/theme-light classes.
prefer-data-theme-docsearch-overrides	—	🟣	Prefer [data-theme] selectors over .navbar--dark when overriding DocSearch styles.
prefer-data-theme-over-prefers-color-scheme	—	🟢 🛡️ 🟣	Prefer Docusaurus data-theme selector scopes over prefers-color-scheme media queries when styling Docusaurus theme tokens or global theme surfaces.
prefer-docsearch-theme-tokens-over-structural-overrides	—	🟣	Prefer curated DocSearch theme tokens over hard-coded structural overrides on common DocSearch UI surfaces.
prefer-infima-theme-tokens-over-structural-overrides	—	🟣	Prefer curated Infima theme tokens over hard-coded structural overrides on common Docusaurus theme surfaces.
prefer-stable-docusaurus-theme-class-names	—	🟣	Prefer documented stable Docusaurus theme class names over attribute-selector fallbacks for known theme components.
require-docsearch-color-mode-pairs	—	🟣	Require paired light/dark DocSearch token override blocks when customizing DocSearch by color mode.
require-docsearch-root-scope-for-docsearch-token-overrides	—	🟣	Require DocSearch token overrides to live on the .DocSearch root scope instead of descendant or non-DocSearch selectors.
require-font-display-on-font-face	—	🟣	Require a font-display declaration in every @font-face block.
require-font-face-local-src-before-remote	—	🟣	Require local() sources to appear before url() sources in @font-face src declarations.
require-html-prefix-for-docusaurus-data-attribute-selectors	—	🟢 🛡️ 🟣	Require an html prefix for bare Docusaurus root data-attribute selectors that target global theme surfaces.
require-ifm-color-primary-scale	—	🟣	Require the full recommended Infima primary color scale when overriding --ifm-color-primary.
require-ifm-color-primary-scale-per-color-mode	—	🟣	Require matching Infima primary color-scale overrides for each Docusaurus color mode you customize.
require-local-anchor-for-global-theme-overrides-in-css-modules	—	🟢 🛡️ 🟣	Require a local selector anchor when overriding Docusaurus global theme surfaces inside CSS Modules.
require-reduced-motion-override-for-interactive-transitions	—	🟣	Require a @media (prefers-reduced-motion) override for interactive selectors that declare transition or animation.

Docusaurus docs CSS guardrails

For real Docusaurus docs CSS surfaces, these third-party rules are commonly noisy: a11y/media-prefers-reduced-motion, defensive-css/require-named-grid-lines, no-descending-specificity, plugin/no-low-performance-animation-properties, order/properties-order, scales/font-sizes.

Recommended pattern: keep explicit docs overrides + narrow inline disable comments with a reason, and enforce both with test/stylelint-docs-guardrails.test.ts.

Documentation

• Overview
• Getting Started
• Current Status
• Configs

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind are welcome.