stylelint · ybiquitous · May 30, 2025 · May 29, 2025 · May 29, 2025 · May 29, 2025
diff --git a/.changeset/huge-ravens-leave.md b/.changeset/huge-ravens-leave.md
@@ -0,0 +1,5 @@
+---
+"stylelint": minor
+---
+
+Added: non-experimental support for functional `message` secondary option
diff --git a/docs/user-guide/configure.md b/docs/user-guide/configure.md
@@ -134,7 +134,7 @@ For example, the following rule configuration would substitute in custom message
 
 Alternately, you can write a [custom formatter](../developer-guide/formatters.md) for maximum control if you need serious customization.
 
-Experimental feature: some rules support message arguments. For example, when configuring the `color-no-hex` rule, the hex color can be used in the message string:
+Some rules support message arguments. For example, when configuring the `color-no-hex` rule, the hex color can be used in the message string:
 
 Via JavaScript:
 
@@ -225,7 +225,7 @@ For example:
 
 Reporters may use these severity levels to display problems or exit the process differently.
 
-Experimental feature: some rules support [message arguments](#message). For these rules, it is possible to use a function for `severity`, which would accept these arguments, allowing you to adjust the severity based on these arguments.
+Some rules support [message arguments](#message). For these rules, it is possible to use a function for `severity`, which would accept these arguments, allowing you to adjust the severity based on these arguments.
 
 This function must return `"error"`, `"warning"`, or `null`. When it would return `null`, the `defaultSeverity` would be used.
 

diff --git a/lib/rules/__tests__/index.test.mjs b/lib/rules/__tests__/index.test.mjs
@@ -60,22 +60,6 @@ describe('deprecated rules', () => {
 	});
 });
 
-describe('custom message option', () => {
-	test.each(ruleNames)(
-		'"%s" should describe a custom message option in the document',
-		async (name) => {
-			const jsCode = await readFile(new URL(`../${name}/index.mjs`, import.meta.url), 'utf8');
-
-			// NOTE: If all rules support a custom message option, we should remove this `if` statement.
-			if (!jsCode.includes('\tmessageArgs: [')) return;
-
-			const doc = await readFile(new URL(`../${name}/README.md`, import.meta.url), 'utf8');
-
-			expect(doc).toContain('`message` secondary option');
-		},
-	);
-});
-
 describe('invalid options', () => {
 	test.each(ruleNames)('"%s" should handle invalid options', async (name) => {
 		const rule = await rules[name];

diff --git a/lib/rules/alpha-value-notation/README.md b/lib/rules/alpha-value-notation/README.md
@@ -11,8 +11,6 @@ Specify percentage or number notation for alpha-values.
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix all of the problems reported by this rule.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `"number"`

diff --git a/lib/rules/annotation-no-unknown/README.md b/lib/rules/annotation-no-unknown/README.md
@@ -11,8 +11,6 @@ a { color: green !imprtant; }
 
 This rule considers annotations defined in the CSS Specifications, up to and including Editor's Drafts, to be known.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `true`

diff --git a/lib/rules/at-rule-allowed-list/README.md b/lib/rules/at-rule-allowed-list/README.md
@@ -11,8 +11,6 @@ Specify a list of allowed at-rules.
 
 This rule ignores the `@charset` rule.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `Array<string>`

diff --git a/lib/rules/at-rule-descriptor-no-unknown/README.md b/lib/rules/at-rule-descriptor-no-unknown/README.md
@@ -17,8 +17,6 @@ You can filter the [CSSTree Syntax Reference](https://csstree.github.io/docs/syn
 
 This rule is only appropriate for CSS. You should not turn it on for CSS-like languages, such as SCSS or Less.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 This rule checks descriptors within at-rules. To check properties, you can use the [`property-no-unknown`](../property-no-unknown/README.md) rule.
 
 For customizing syntax, see the [`languageOptions`](../../../docs/user-guide/configure.md#languageoptions) section.

diff --git a/lib/rules/at-rule-descriptor-value-no-unknown/README.md b/lib/rules/at-rule-descriptor-value-no-unknown/README.md
@@ -17,8 +17,6 @@ You can filter the [CSSTree Syntax Reference](https://csstree.github.io/docs/syn
 
 This rule is only appropriate for CSS. You should not turn it on for CSS-like languages, such as SCSS or Less.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 This rule checks descriptor values within at-rules. You can use [`declaration-property-value-no-unknown`](../declaration-property-value-no-unknown/README.md) to disallow unknown values for properties within declarations, and [`at-rule-descriptor-no-unknown`](../at-rule-descriptor-no-unknown/README.md) to disallow unknown descriptors for at-rules.
 
 This rule overlaps with:

diff --git a/lib/rules/at-rule-disallowed-list/README.md b/lib/rules/at-rule-disallowed-list/README.md
@@ -11,8 +11,6 @@ Specify a list of disallowed at-rules.
 
 This rule ignores the `@charset` rule.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `Array<string>`

diff --git a/lib/rules/at-rule-empty-line-before/index.cjs b/lib/rules/at-rule-empty-line-before/index.cjs
diff --git a/lib/rules/at-rule-empty-line-before/index.mjs b/lib/rules/at-rule-empty-line-before/index.mjs
@@ -150,6 +150,7 @@ const rule = (primary, secondaryOptions, context) => {
 
 			report({
 				message,
+				messageArgs: [],
 				node: atRule,
 				result,
 				ruleName,

diff --git a/lib/rules/at-rule-no-deprecated/README.md b/lib/rules/at-rule-no-deprecated/README.md
@@ -19,8 +19,6 @@ This rule flags at-rules that were removed or deprecated after being in the CSS
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix some of the problems reported by this rule.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) accept arguments.
-
 Prior art:
 
 - [@csstools/stylelint-no-at-nest-rule](https://www.npmjs.com/package/@csstools/stylelint-no-at-nest-rule)

diff --git a/lib/rules/at-rule-no-unknown/README.md b/lib/rules/at-rule-no-unknown/README.md
@@ -11,8 +11,6 @@ Disallow unknown at-rules.
 
 This rule considers at-rules defined in the CSS Specifications, up to and including Editor's Drafts, to be known.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 For customizing syntax, see the [`languageOptions`](../../../docs/user-guide/configure.md#languageoptions) section.
 
 ## Options

diff --git a/lib/rules/at-rule-no-vendor-prefix/README.md b/lib/rules/at-rule-no-vendor-prefix/README.md
@@ -13,8 +13,6 @@ This rule ignores non-standard vendor-prefixed at-rules that aren't handled by [
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix all of the problems reported by this rule. However, it will not remove duplicate at-rules produced when the prefixes are removed. You can use [Autoprefixer](https://github.com/postcss/autoprefixer) itself, with the [`add` option off and the `remove` option on](https://github.com/postcss/autoprefixer#options), in these situations.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `true`

diff --git a/lib/rules/at-rule-prelude-no-invalid/README.md b/lib/rules/at-rule-prelude-no-invalid/README.md
@@ -15,8 +15,6 @@ You can filter the [CSSTree Syntax Reference](https://csstree.github.io/docs/syn
 
 This rule is only appropriate for CSS. You should not turn it on for CSS-like languages, such as SCSS or Less.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 This rule overlaps with:
 
 - [`media-query-no-invalid`](../media-query-no-invalid/README.md)

diff --git a/lib/rules/at-rule-property-required-list/README.md b/lib/rules/at-rule-property-required-list/README.md
@@ -9,8 +9,6 @@ Specify a list of required properties (or descriptors) for an at-rule.
  *  At-rule and required descriptor names */
 ```
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `Array<string>`

diff --git a/lib/rules/block-no-empty/index.cjs b/lib/rules/block-no-empty/index.cjs
diff --git a/lib/rules/block-no-empty/index.mjs b/lib/rules/block-no-empty/index.mjs
@@ -73,6 +73,7 @@ const rule = (primary, secondaryOptions, context) => {
 
 			report({
 				message: messages.rejected,
+				messageArgs: [],
 				node: statement,
 				start: statement.positionBy({ index }),
 				end: statement.rangeBy({}).end,

diff --git a/lib/rules/color-function-alias-notation/README.md b/lib/rules/color-function-alias-notation/README.md
@@ -13,8 +13,6 @@ Color functions `rgb()` and `hsl()` have aliases `rgba()` and `hsla()`. Those ar
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix all of the problems reported by this rule.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `"without-alpha"`

diff --git a/lib/rules/color-function-notation/README.md b/lib/rules/color-function-notation/README.md
@@ -15,8 +15,6 @@ For legacy reasons, `rgb()` and `hsl()` also supports an alternate syntax that s
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix some of the problems reported by this rule when the primary option is `"modern"`.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `"modern"`

diff --git a/lib/rules/color-hex-alpha/README.md b/lib/rules/color-hex-alpha/README.md
@@ -9,8 +9,6 @@ a { color: #fffa }
  * This alpha channel */
 ```
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `"always"`

diff --git a/lib/rules/color-hex-length/README.md b/lib/rules/color-hex-length/README.md
@@ -11,8 +11,6 @@ a { color: #fff }
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix all of the problems reported by this rule.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `"short"`

diff --git a/lib/rules/color-named/index.cjs b/lib/rules/color-named/index.cjs
diff --git a/lib/rules/color-named/index.mjs b/lib/rules/color-named/index.mjs
@@ -169,6 +169,7 @@ const rule = (primary, secondaryOptions) => {
 				result,
 				ruleName,
 				message,
+				messageArgs: [],
 				node,
 				index,
 				endIndex: index + length,

diff --git a/lib/rules/color-no-hex/README.md b/lib/rules/color-no-hex/README.md
@@ -9,8 +9,6 @@ a { color: #333 }
  * This hex color */
 ```
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `true`

diff --git a/lib/rules/color-no-invalid-hex/README.md b/lib/rules/color-no-invalid-hex/README.md
@@ -11,8 +11,6 @@ a { color: #y3 }
 
 Longhand hex colors can be either 6 or 8 (with alpha channel) hexadecimal characters. And their shorthand variants are 3 and 4 characters respectively.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 This rule overlaps with:
 
 - [`at-rule-descriptor-value-no-unknown`](../at-rule-descriptor-value-no-unknown/README.md)

diff --git a/lib/rules/comment-empty-line-before/index.cjs b/lib/rules/comment-empty-line-before/index.cjs
diff --git a/lib/rules/comment-empty-line-before/index.mjs b/lib/rules/comment-empty-line-before/index.mjs
@@ -112,6 +112,7 @@ const rule = (primary, secondaryOptions, context) => {
 
 			report({
 				message,
+				messageArgs: [],
 				node: comment,
 				result,
 				ruleName,

diff --git a/lib/rules/comment-no-empty/index.cjs b/lib/rules/comment-no-empty/index.cjs
diff --git a/lib/rules/comment-no-empty/index.mjs b/lib/rules/comment-no-empty/index.mjs
@@ -35,6 +35,7 @@ const rule = (primary) => {
 
 			report({
 				message: messages.rejected,
+				messageArgs: [],
 				node: comment,
 				result,
 				ruleName,

diff --git a/lib/rules/comment-pattern/README.md b/lib/rules/comment-pattern/README.md
@@ -9,8 +9,6 @@ Specify a pattern for comments.
  * The pattern of this */
 ```
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `string`

diff --git a/lib/rules/comment-whitespace-inside/index.cjs b/lib/rules/comment-whitespace-inside/index.cjs
diff --git a/lib/rules/comment-whitespace-inside/index.mjs b/lib/rules/comment-whitespace-inside/index.mjs
@@ -127,6 +127,7 @@ const rule = (primary) => {
 
 				report({
 					message,
+					messageArgs: [],
 					index,
 					endIndex,
 					result,

diff --git a/lib/rules/comment-word-disallowed-list/README.md b/lib/rules/comment-word-disallowed-list/README.md
@@ -12,8 +12,6 @@ Specify a list of disallowed words within comments.
 > [!WARNING]
 > Comments within _selector and value lists_ are currently ignored.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `Array<string>`

diff --git a/lib/rules/container-name-pattern/README.md b/lib/rules/container-name-pattern/README.md
@@ -9,8 +9,6 @@ Specify a pattern for container names.
  * The pattern of this */
 ```
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `string`

diff --git a/lib/rules/custom-media-pattern/README.md b/lib/rules/custom-media-pattern/README.md
@@ -9,8 +9,6 @@ Specify a pattern for custom media query names.
  * The pattern of this */
 ```
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `string`

diff --git a/lib/rules/custom-property-empty-line-before/index.cjs b/lib/rules/custom-property-empty-line-before/index.cjs
diff --git a/lib/rules/custom-property-empty-line-before/index.mjs b/lib/rules/custom-property-empty-line-before/index.mjs
@@ -113,6 +113,7 @@ const rule = (primary, secondaryOptions, context) => {
 
 			report({
 				message,
+				messageArgs: [],
 				node: decl,
 				result,
 				ruleName,

diff --git a/lib/rules/custom-property-no-missing-var-function/README.md b/lib/rules/custom-property-no-missing-var-function/README.md
@@ -15,8 +15,6 @@ This rule has the following limitations:
 - It only reports custom properties that are defined within the same source.
 - It does not check properties that can contain author-defined identifiers, e.g. `transition-property`.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `true`

diff --git a/lib/rules/custom-property-pattern/README.md b/lib/rules/custom-property-pattern/README.md
@@ -9,8 +9,6 @@ a { --foo-: 1px; }
  * The pattern of this */
 ```
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `string`

diff --git a/lib/rules/declaration-block-no-duplicate-custom-properties/README.md b/lib/rules/declaration-block-no-duplicate-custom-properties/README.md
@@ -11,8 +11,6 @@ a { --custom-property: pink; --custom-property: orange; }
 
 This rule is case-sensitive.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `true`

diff --git a/lib/rules/declaration-block-no-duplicate-properties/README.md b/lib/rules/declaration-block-no-duplicate-properties/README.md
@@ -13,8 +13,6 @@ This rule ignores variables (`$sass`, `@less`, `--custom-property`).
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix all of the problems reported by this rule.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `true`

diff --git a/lib/rules/declaration-block-no-redundant-longhand-properties/README.md b/lib/rules/declaration-block-no-redundant-longhand-properties/README.md
@@ -92,8 +92,6 @@ Flexbox-related properties can be ignored using `ignoreShorthands: ["/flex/"]` (
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix most of the problems reported by this rule.
 
-The [`message` secondary option](../../../docs/user-guide/configure.md#message) can accept the arguments of this rule.
-
 ## Options
 
 ### `true`