Skip to main content

docusaurus-docs-safe

docusaurusPluginConfigs["docusaurus-docs-safe"] is an opinionated preset intended for teams linting Docusaurus docs surfaces.

Usageโ€‹

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

export default docusaurusPluginConfigs["docusaurus-docs-safe"];

What it enablesโ€‹

This preset currently mirrors docusaurusPluginConfigs["docusaurus-recommended"] for all public docusaurus/* plugin rules.

Its purpose is to provide a stable home for Docusaurus docs-surface guidance without forcing third-party rule dependencies into this package runtime.

Docusaurus docs CSS guardrails (important)โ€‹

When linting real Docusaurus docs CSS (for example custom.css and index.module.css), some third-party rules are intentionally noisy and should be handled with targeted overrides plus justified inline stylelint-disable ... -- reason comments.

Known trap-prone rules:

  • 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

Suggested approach:

  1. Keep docs overrides explicit in your Stylelint config.
  2. Use narrow file-level disables with -- reason for intentional exceptions.
  3. Add a CI guardrail test that verifies both of the above.

Rules in this configโ€‹

Fix legend: ๐Ÿ”ง = autofixable ยท โ€” = report only

RuleFixDescription
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-subtree-data-theme-selectorsโ€”Disallow subtree-scoped data-theme selectors that do not start from the Docusaurus root color-mode attribute.
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-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.
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-local-anchor-for-global-theme-overrides-in-css-modulesโ€”Require a local selector anchor when overriding Docusaurus global theme surfaces inside CSS Modules.