eslint-community · bmish · Jan 1, 2026 · Jan 1, 2026 · Jan 1, 2026 · Jan 1, 2026
diff --git a/README.md b/README.md
@@ -185,11 +185,11 @@ There's also a `postprocess` option that's only available via a [config file](#c
 | `--init-rule-docs` | Whether to create rule doc files if they don't yet exist. | `false` |
 | `--path-rule-doc` | Path to markdown file for each rule doc. Use `{name}` placeholder for the rule name. A function can also be provided for this option via a [config file](#configuration-file). | `docs/rules/{name}.md` |
 | `--path-rule-list` | Path to markdown file where the rules table list should live. Option can be repeated. | `README.md` |
-| `--rule-doc-notices` | Ordered, comma-separated list of notices to display in rule doc. Non-applicable notices will be hidden. See choices in below [table](#column-and-notice-types). | `configs`, `deprecated`, `fixableAndHasSuggestions`, `requiresTypeChecking` |
+| `--rule-doc-notices` | Ordered, comma-separated list of notices to display in rule doc. Non-applicable notices will be hidden. See choices in below [table](#column-and-notice-types). | `configs`, `deprecated`, `fixableAndHasSuggestions`, `requiresTypeChecking`, `description` |
 | `--rule-doc-section-exclude` | Disallowed section in each rule doc. Exit with failure if present. Option can be repeated. | |
 | `--rule-doc-section-include` | Required section in each rule doc. Exit with failure if missing. Option can be repeated. | |
 | `--rule-doc-section-options` | Whether to require an "Options" or "Config" rule doc section and mention of any named options for rules with options. | `true` |
-| `--rule-doc-title-format` | The format to use for rule doc titles. See choices in below [table](#--rule-doc-title-format). | `desc-parens-prefix-name` |
+| `--rule-doc-title-format` | The format to use for rule doc titles. See choices in below [table](#--rule-doc-title-format). | `prefix-name` |
 | `--rule-list-columns` | Ordered, comma-separated list of columns to display in rule list. Empty columns will be hidden. See choices in below [table](#column-and-notice-types). | `name`, `description`, `configsError`, `configsWarn`, `configsOff`, `fixable`, `hasSuggestions`, `requiresTypeChecking`, `deprecated` |
 | `--rule-list-split` | Rule property(s) to split the rules list by. A separate list and header will be created for each value. Example: `meta.type`. A function can also be provided for this option via a [config file](#configuration-file). | |
 | `--url-configs` | Link to documentation about the ESLint configurations exported by the plugin. | |
@@ -206,7 +206,7 @@ These are the types of rule metadata that are available for display in rule list
 | ⚠️ | `configsWarn` | Yes | No | Whether a rule is set to `warn` in a config. |
 | 💼 | `configs` | No | Yes | What configs set a rule to what [severities](https://eslint.org/docs/latest/user-guide/configuring/rules#rule-severities). |
 | ❌ | `deprecated` | Yes | Yes | Whether a rule is deprecated (i.e. likely to be removed/renamed in a future major version). |
-| | `description` | Yes | Yes | The rule description. |
+| 📝 | `description` | Yes | Yes | The rule description. |
 | 🔧💡 | `fixableAndHasSuggestions` | Yes | Yes | Whether a rule is [fixable](https://eslint.org/docs/latest/developer-guide/working-with-rules#applying-fixes) and/or has [suggestions](https://eslint.org/docs/latest/developer-guide/working-with-rules#providing-suggestions). |
 | 🔧 | `fixable` | Yes | Yes | Whether a rule is [fixable](https://eslint.org/docs/latest/developer-guide/working-with-rules#applying-fixes). |
 | 💡 | `hasSuggestions` | Yes | Yes | Whether a rule has [suggestions](https://eslint.org/docs/latest/developer-guide/working-with-rules#providing-suggestions). |
@@ -233,9 +233,9 @@ Where `no-foo` is the rule name, `Disallow use of foo` is the rule description,
 | :-- | :-- |
 | `desc` | `# Disallow use of foo` |
 | `desc-parens-name` | `# Disallow use of foo (no-foo)` |
-| `desc-parens-prefix-name` (default) | `# Disallow use of foo (test/no-foo)` |
+| `desc-parens-prefix-name` | `# Disallow use of foo (test/no-foo)` |
 | `name` | `# no-foo` |
-| `prefix-name` | `# test/no-foo` |
+| `prefix-name` (default) | `# test/no-foo` |
 
 ### Configuration file
 

diff --git a/docs/examples/eslint-plugin-test/docs/rules/no-foo.md b/docs/examples/eslint-plugin-test/docs/rules/no-foo.md
@@ -1,4 +1,4 @@
-# Disallow using foo (`test/no-foo`)
+# test/no-foo
 
 💼 This rule is enabled in the ✅ `recommended` config.
 
@@ -10,6 +10,8 @@
 
 ❗ This rule identifies problems that could cause errors or unexpected behavior.
 
+📝 Disallow using foo.
+
 <!-- end auto-generated rule header -->
 
 ## Rule details

diff --git a/docs/examples/eslint-plugin-test/docs/rules/prefer-bar.md b/docs/examples/eslint-plugin-test/docs/rules/prefer-bar.md
@@ -1,4 +1,4 @@
-# Enforce using bar (`test/prefer-bar`)
+# test/prefer-bar
 
 💼⚠️ This rule is enabled in the ✅ `recommended` config. This rule _warns_ in the 🎨 `stylistic` config.
 
@@ -8,6 +8,8 @@
 
 📖 This rule identifies potential improvements.
 
+📝 Enforce using bar.
+
 <!-- end auto-generated rule header -->
 
 ## Rule details

diff --git a/docs/examples/eslint-plugin-test/docs/rules/require-baz.md b/docs/examples/eslint-plugin-test/docs/rules/require-baz.md
@@ -1,4 +1,4 @@
-# Require using baz (`test/require-baz`)
+# test/require-baz
 
 ❌ This rule is deprecated. It was replaced by [`test/prefer-bar`](prefer-bar.md).
 
@@ -8,6 +8,8 @@
 
 📏 This rule focuses on code formatting.
 
+📝 Require using baz.
+
 <!-- end auto-generated rule header -->
 
 ## Rule details

diff --git a/lib/emojis.ts b/lib/emojis.ts
@@ -69,6 +69,9 @@ export const EMOJI_TYPE = '🗂️';
 /** Rule is deprecated (from `meta.deprecated`). */
 export const EMOJI_DEPRECATED = '❌';
 
+/** Rule description (from `meta.docs.description`). */
+export const EMOJI_DESCRIPTION = '📝';
+
 /**
  * The user is not allowed to specify a reserved emoji to represent their config because we use these emojis for other purposes.
  * Note that the default emojis for common configs are intentionally not reserved.
@@ -83,4 +86,5 @@ export const RESERVED_EMOJIS = [
   EMOJI_REQUIRES_TYPE_CHECKING,
   EMOJI_TYPE,
   EMOJI_DEPRECATED,
+  EMOJI_DESCRIPTION,
 ];
diff --git a/lib/options.ts b/lib/options.ts
@@ -46,12 +46,11 @@ export const NOTICE_TYPE_DEFAULT_PRESENCE_AND_ORDERING: {
   [NOTICE_TYPE.OPTIONS]: false,
   [NOTICE_TYPE.REQUIRES_TYPE_CHECKING]: true,
   [NOTICE_TYPE.TYPE]: false,
-  [NOTICE_TYPE.DESCRIPTION]: false,
+  [NOTICE_TYPE.DESCRIPTION]: true,
 };
 
 // Using these variables ensures they have the correct type (not just a plain string).
-const DEFAULT_RULE_DOC_TITLE_FORMAT: RuleDocTitleFormat =
-  'desc-parens-prefix-name';
+const DEFAULT_RULE_DOC_TITLE_FORMAT: RuleDocTitleFormat = 'prefix-name';
 const DEFAULT_CONFIG_FORMAT: ConfigFormat = 'name';
 
 export const OPTION_DEFAULTS = {

diff --git a/lib/rule-doc-notices.ts b/lib/rule-doc-notices.ts
@@ -1,6 +1,7 @@
 import { END_RULE_HEADER_MARKER } from './comment-markers.js';
 import {
   EMOJI_DEPRECATED,
+  EMOJI_DESCRIPTION,
   EMOJI_FIXABLE,
   EMOJI_HAS_SUGGESTIONS,
   EMOJI_REQUIRES_TYPE_CHECKING,
@@ -199,7 +200,7 @@ const RULE_NOTICES: {
     }
 
     // Return the description like a normal body sentence.
-    return addTrailingPeriod(toSentenceCase(description));
+    return `${EMOJI_DESCRIPTION} ${addTrailingPeriod(toSentenceCase(description))}`;
   },
 
   [NOTICE_TYPE.TYPE]: ({ type }) => {

diff --git a/lib/types.ts b/lib/types.ts
@@ -218,7 +218,7 @@ export type GenerateOptions = {
   /** Whether to require an "Options" or "Config" rule doc section and mention of any named options for rules with options. Default: `true`. */
   readonly ruleDocSectionOptions?: boolean;
 
-  /** The format to use for rule doc titles. Default: `desc-parens-prefix-name`. */
+  /** The format to use for rule doc titles. Default: `prefix-name`. */
   readonly ruleDocTitleFormat?: RuleDocTitleFormat;
 
   /**

diff --git a/test/fixtures/cjs-config-extends/docs/rules/no-bar.md b/test/fixtures/cjs-config-extends/docs/rules/no-bar.md
@@ -1,5 +1,7 @@
-# Description of no-bar (`test/no-bar`)
+# test/no-bar
 
 💼 This rule is enabled in the ✅ `recommended` config.
 
+📝 Description of no-bar.
+
 <!-- end auto-generated rule header -->
diff --git a/test/fixtures/cjs-config-extends/docs/rules/no-baz.md b/test/fixtures/cjs-config-extends/docs/rules/no-baz.md
@@ -1,5 +1,7 @@
-# Description of no-baz (`test/no-baz`)
+# test/no-baz
 
 💼 This rule is enabled in the ✅ `recommended` config.
 
+📝 Description of no-baz.
+
 <!-- end auto-generated rule header -->
diff --git a/test/fixtures/cjs-config-extends/docs/rules/no-biz.md b/test/fixtures/cjs-config-extends/docs/rules/no-biz.md
@@ -1,5 +1,7 @@
-# Description of no-biz (`test/no-biz`)
+# test/no-biz
 
 💼 This rule is enabled in the ✅ `recommended` config.
 
+📝 Description of no-biz.
+
 <!-- end auto-generated rule header -->
diff --git a/test/fixtures/cjs-config-extends/docs/rules/no-foo.md b/test/fixtures/cjs-config-extends/docs/rules/no-foo.md
@@ -1,5 +1,7 @@
-# Description of no-foo (`test/no-foo`)
+# test/no-foo
 
 💼 This rule is enabled in the ✅ `recommended` config.
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
diff --git a/test/fixtures/cjs/docs/rules/no-foo.md b/test/fixtures/cjs/docs/rules/no-foo.md
@@ -1,3 +1,5 @@
-# Disallow foo (`test/no-foo`)
+# test/no-foo
+
+📝 Disallow foo.
 
 <!-- end auto-generated rule header -->
diff --git a/test/lib/generate/__snapshots__/cjs-test.ts.snap b/test/lib/generate/__snapshots__/cjs-test.ts.snap
@@ -14,7 +14,9 @@ exports[`generate (cjs) basic generates the documentation 1`] = `
 `;
 
 exports[`generate (cjs) basic generates the documentation 2`] = `
-"# Disallow foo (\`test/no-foo\`)
+"# test/no-foo
+
+📝 Disallow foo.
 
 <!-- end auto-generated rule header -->
 "
@@ -42,37 +44,45 @@ exports[`generate (cjs) config that extends another config generates the documen
 `;
 
 exports[`generate (cjs) config that extends another config generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (cjs) config that extends another config generates the documentation 3`] = `
-"# Description of no-bar (\`test/no-bar\`)
+"# test/no-bar
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description of no-bar.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (cjs) config that extends another config generates the documentation 4`] = `
-"# Description of no-baz (\`test/no-baz\`)
+"# test/no-baz
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description of no-baz.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (cjs) config that extends another config generates the documentation 5`] = `
-"# Description of no-biz (\`test/no-biz\`)
+"# test/no-biz
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description of no-biz.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/comment-markers-test.ts.snap b/test/lib/generate/__snapshots__/comment-markers-test.ts.snap
@@ -38,10 +38,12 @@ exports[`generate (comment markers) no existing comment markers - minimal doc co
 `;
 
 exports[`generate (comment markers) no existing comment markers - minimal doc content generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 🔧 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -54,10 +56,12 @@ title: "plugin/rule-name"
 description: "disallow foo"
 since: "v0.12.0"
 ---
-# Description (\`test/no-foo\`)
+# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 Pre-existing notice about the rule being recommended.
 ## Rule details
@@ -79,10 +83,12 @@ Existing rules section content."
 `;
 
 exports[`generate (comment markers) no existing comment markers - with no blank lines in existing content generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 🔧 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 Existing rule doc content."
 `;
@@ -103,10 +109,12 @@ Existing rules section content."
 `;
 
 exports[`generate (comment markers) no existing comment markers - with one blank line around existing content generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 🔧 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 
 Existing rule doc content."
@@ -120,10 +128,12 @@ title: "plugin/rule-name"
 description: "disallow foo"
 since: "v0.12.0"
 ---
-# Description (\`test/no-foo\`)
+# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 ## Rule details
 Details."
@@ -137,19 +147,23 @@ title: "plugin/rule-name"
 description: "disallow foo"
 since: "v0.12.0"
 ---
-# Description (\`test/no-foo\`)
+# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (comment markers) rule doc without header marker but pre-existing header updates the documentation 1`] = `
-"# Description (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 Pre-existing notice about the rule being recommended.
 ## Rule details
@@ -173,10 +187,12 @@ No blank line before this."
 `;
 
 exports[`generate (comment markers) with no blank lines around comment markers generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 🔧 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 No blank line before this."
 `;
@@ -200,10 +216,12 @@ One blank line before this."
 `;
 
 exports[`generate (comment markers) with one blank line around comment markers generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 🔧 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 
 One blank line before this."