From d8c0276af77ca5aa984b49368869931daeea0a81 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Thu, 1 Jan 2026 15:20:09 -0500
Subject: [PATCH 1/5] feat: change rule doc title to prefix and rule name and
 add default rule description notice

---
 README.md                                     | 10 +--
 lib/emojis.ts                                 |  4 ++
 lib/options.ts                                |  7 +-
 lib/rule-doc-notices.ts                       |  3 +-
 lib/types.ts                                  |  2 +-
 test/fixtures/cjs-config-extends/README.md    |  8 +--
 .../cjs-config-extends/docs/rules/no-bar.md   |  4 +-
 .../cjs-config-extends/docs/rules/no-baz.md   |  4 +-
 .../cjs-config-extends/docs/rules/no-biz.md   |  4 +-
 .../cjs-config-extends/docs/rules/no-foo.md   |  4 +-
 test/fixtures/cjs/docs/rules/no-foo.md        |  4 +-
 .../comment-markers-test.ts.snap              | 36 +++++++---
 .../__snapshots__/configs-test.ts.snap        | 68 ++++++++++++++-----
 .../__snapshots__/general-test.ts.snap        | 24 +++++--
 .../__snapshots__/option-check-test.ts.snap   |  7 +-
 .../option-config-emoji-test.ts.snap          | 20 ++++--
 .../option-config-format-test.ts.snap         | 12 +++-
 .../option-rule-doc-notices-test.ts.snap      |  4 +-
 .../option-rule-doc-title-format-test.ts.snap | 10 +++
 .../option-rule-list-columns-test.ts.snap     | 12 +++-
 .../option-url-configs-test.ts.snap           | 12 +++-
 .../option-url-rule-doc-test.ts.snap          | 24 +++++--
 .../__snapshots__/package-json-test.ts.snap   | 16 +++--
 .../rule-deprecation-test.ts.snap             | 56 +++++++++++----
 .../rule-description-test.ts.snap             | 16 +++--
 25 files changed, 272 insertions(+), 99 deletions(-)

diff --git a/README.md b/README.md
index 45213bb8..7a0cd4ed 100644
--- 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/lib/emojis.ts b/lib/emojis.ts
index 27433edd..477ab0b1 100644
--- 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
index fb6b4275..ba1adf9c 100644
--- a/lib/options.ts
+++ b/lib/options.ts
@@ -38,20 +38,19 @@ export const NOTICE_TYPE_DEFAULT_PRESENCE_AND_ORDERING: {
 } = {
   // Object keys ordered in display order.
   // Object values indicate whether the column is displayed by default.
-  [NOTICE_TYPE.DEPRECATED]: true, // Most important.
   [NOTICE_TYPE.CONFIGS]: true,
+  [NOTICE_TYPE.DEPRECATED]: true, // Most important.
   [NOTICE_TYPE.FIXABLE]: false,
   [NOTICE_TYPE.FIXABLE_AND_HAS_SUGGESTIONS]: true, // Default, consolidated notice.
   [NOTICE_TYPE.HAS_SUGGESTIONS]: false,
   [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
index c43547da..8d345ffd 100644
--- 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
index 10406a21..796b2946 100644
--- 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/README.md b/test/fixtures/cjs-config-extends/README.md
index 95c16095..83499ecb 100644
--- a/test/fixtures/cjs-config-extends/README.md
+++ b/test/fixtures/cjs-config-extends/README.md
@@ -9,9 +9,9 @@
 
 | Name                           | Description            | 💼 |
 | :----------------------------- | :--------------------- | :- |
-| [no-bar](docs/rules/no-bar.md) | Description of no-bar. | ✅ |
-| [no-baz](docs/rules/no-baz.md) | Description of no-baz. | ✅ |
-| [no-biz](docs/rules/no-biz.md) | Description of no-biz. | ✅ |
-| [no-foo](docs/rules/no-foo.md) | Description of no-foo. | ✅ |
+| [no-bar](docs/rules/no-bar.md) | Description of no-bar. | ✅  |
+| [no-baz](docs/rules/no-baz.md) | Description of no-baz. | ✅  |
+| [no-biz](docs/rules/no-biz.md) | Description of no-biz. | ✅  |
+| [no-foo](docs/rules/no-foo.md) | Description of no-foo. | ✅  |
 
 <!-- end auto-generated rules list -->
diff --git a/test/fixtures/cjs-config-extends/docs/rules/no-bar.md b/test/fixtures/cjs-config-extends/docs/rules/no-bar.md
index e50f4ca1..3849708a 100644
--- 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
index 1200417c..af604ccb 100644
--- 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
index 5ca6aee0..1eb94cf5 100644
--- 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
index 51e6f39b..e1c76e1e 100644
--- 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
index cb638771..5b71e669 100644
--- 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__/comment-markers-test.ts.snap b/test/lib/generate/__snapshots__/comment-markers-test.ts.snap
index 7495249d..9142fdf3 100644
--- 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."
diff --git a/test/lib/generate/__snapshots__/configs-test.ts.snap b/test/lib/generate/__snapshots__/configs-test.ts.snap
index 59411d50..434b9ce8 100644
--- a/test/lib/generate/__snapshots__/configs-test.ts.snap
+++ b/test/lib/generate/__snapshots__/configs-test.ts.snap
@@ -15,19 +15,23 @@ exports[`generate (configs) config as flat config updates the documentation 1`]
 `;
 
 exports[`generate (configs) config as flat config updates 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 (configs) config as flat config updates 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 -->
 "
 `;
@@ -48,10 +52,12 @@ exports[`generate (configs) config with overrides generates the documentation 1`
 `;
 
 exports[`generate (configs) config with overrides 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 -->
 "
 `;
@@ -70,10 +76,12 @@ exports[`generate (configs) only a \`recommended\` config updates the documentat
 `;
 
 exports[`generate (configs) only a \`recommended\` config updates the documentation 2`] = `
-"# Description (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -94,10 +102,12 @@ exports[`generate (configs) rule config with options generates the documentation
 `;
 
 exports[`generate (configs) rule config with options 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 -->
 "
 `;
@@ -127,64 +137,78 @@ exports[`generate (configs) rules that are disabled or set to warn generates the
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 🚫 This rule is _disabled_ in the 🔥 \`recommended\` config.
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn generates the documentation 3`] = `
-"# Description of no-bar (\`test/no-bar\`)
+"# test/no-bar
 
 🚫 This rule is _disabled_ in the following configs: 🌟 \`other\`, 🔥 \`recommended\`.
 
+📝 Description of no-bar.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn generates the documentation 4`] = `
-"# Description of no-baz (\`test/no-baz\`)
+"# test/no-baz
 
 💼🚫 This rule is enabled in the 🔥 \`recommended\` config. This rule is _disabled_ in the 🌟 \`other\` config.
 
+📝 Description of no-baz.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn generates the documentation 5`] = `
-"# Description of no-biz (\`test/no-biz\`)
+"# test/no-biz
 
 🚫 This rule is _disabled_ in the 🌟 \`other\` config.
 
+📝 Description of no-biz.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn generates the documentation 6`] = `
-"# Description of no-boz (\`test/no-boz\`)
+"# test/no-boz
 
 ⚠️ This rule _warns_ in the 🔥 \`recommended\` config.
 
+📝 Description of no-boz.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn generates the documentation 7`] = `
-"# Description of no-buz (\`test/no-buz\`)
+"# test/no-buz
 
 ⚠️ This rule _warns_ in the following configs: 🌟 \`other\`, 🔥 \`recommended\`.
 
+📝 Description of no-buz.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn generates the documentation 8`] = `
-"# Description of no-bez (\`test/no-bez\`)
+"# test/no-bez
 
 ⚠️ This rule _warns_ in the 🌟 \`other\` config.
 
+📝 Description of no-bez.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -207,19 +231,23 @@ exports[`generate (configs) rules that are disabled or set to warn, only one con
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn, only one config present generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 ⚠️ This rule _warns_ in the ✅ \`recommended\` config.
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn, only one config present generates the documentation 3`] = `
-"# Description of no-bar (\`test/no-bar\`)
+"# test/no-bar
 
 🚫 This rule is _disabled_ in the ✅ \`recommended\` config.
 
+📝 Description of no-bar.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -242,10 +270,12 @@ exports[`generate (configs) rules that are disabled or set to warn, two configs
 `;
 
 exports[`generate (configs) rules that are disabled or set to warn, two configs present generates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 ⚠️🚫 This rule _warns_ in the ✅ \`recommended\` config. This rule is _disabled_ in the ⌨️ \`typescript\` config.
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -266,10 +296,12 @@ exports[`generate (configs) with --ignore-config hides the ignored config 1`] =
 `;
 
 exports[`generate (configs) with --ignore-config hides the ignored config 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -290,10 +322,12 @@ exports[`generate (configs) with config that does not have any rules uses recomm
 `;
 
 exports[`generate (configs) with config that does not have any rules uses recommended config emoji since it is the only relevant config 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/general-test.ts.snap b/test/lib/generate/__snapshots__/general-test.ts.snap
index a15e62c7..79cc9104 100644
--- a/test/lib/generate/__snapshots__/general-test.ts.snap
+++ b/test/lib/generate/__snapshots__/general-test.ts.snap
@@ -24,12 +24,14 @@ more content."
 `;
 
 exports[`generate (general) basic updates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the following configs: 🌐 \`all\`, ✅ \`recommended\`.
 
 🔧💡 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) and manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 ## Rule details
 details
@@ -39,19 +41,23 @@ optionToDoSomething2 - explanation"
 `;
 
 exports[`generate (general) basic updates the documentation 3`] = `
-"# Description of no-bar (\`test/no-bar\`)
+"# test/no-bar
 
 💼 This rule is enabled in the following configs: 🌐 \`all\`, 🎨 \`style\`.
 
 🔧 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
+📝 Description of no-bar.
+
 <!-- end auto-generated rule header -->
 ## Rule details
 details"
 `;
 
 exports[`generate (general) basic updates the documentation 4`] = `
-"# Description of no-boz (\`test/no-baz\`)
+"# test/no-baz
+
+📝 Description of no-boz.
 
 <!-- end auto-generated rule header -->
 ## Rule details
@@ -78,10 +84,12 @@ more content."
 `;
 
 exports[`generate (general) plugin prefix uses \`plugin.meta.name\` as source for rule prefix 2`] = `
-"# Description of no-foo (\`custom/no-foo\`)
+"# custom/no-foo
 
 🔧💡 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) and manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 ## Rule details
 details
@@ -91,17 +99,21 @@ optionToDoSomething2 - explanation"
 `;
 
 exports[`generate (general) plugin prefix uses \`plugin.meta.name\` as source for rule prefix 3`] = `
-"# Description of no-bar (\`custom/no-bar\`)
+"# custom/no-bar
 
 🔧 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
 
+📝 Description of no-bar.
+
 <!-- end auto-generated rule header -->
 ## Rule details
 details"
 `;
 
 exports[`generate (general) plugin prefix uses \`plugin.meta.name\` as source for rule prefix 4`] = `
-"# Description of no-boz (\`custom/no-baz\`)
+"# custom/no-baz
+
+📝 Description of no-boz.
 
 <!-- end auto-generated rule header -->
 ## Rule details
diff --git a/test/lib/generate/__snapshots__/option-check-test.ts.snap b/test/lib/generate/__snapshots__/option-check-test.ts.snap
index 2587d390..0a894b67 100644
--- a/test/lib/generate/__snapshots__/option-check-test.ts.snap
+++ b/test/lib/generate/__snapshots__/option-check-test.ts.snap
@@ -5,11 +5,12 @@ exports[`generate (--check) basic prints the issues, exits with failure, and doe
   "- Expected
 + Received
 
-- # Description for no-foo (\`test/no-foo\`)
+  # test/no-foo
 -
-- <!-- end auto-generated rule header -->
+- 📝 Description for no-foo.
 -
-+ # test/no-foo",
+- <!-- end auto-generated rule header -->
+-",
 ]
 `;
 
diff --git a/test/lib/generate/__snapshots__/option-config-emoji-test.ts.snap b/test/lib/generate/__snapshots__/option-config-emoji-test.ts.snap
index d78d5750..1e964b28 100644
--- a/test/lib/generate/__snapshots__/option-config-emoji-test.ts.snap
+++ b/test/lib/generate/__snapshots__/option-config-emoji-test.ts.snap
@@ -20,28 +20,34 @@ exports[`generate (--config-emoji) basic shows the correct emojis 1`] = `
 `;
 
 exports[`generate (--config-emoji) basic shows the correct emojis 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the 🔥 \`recommended\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (--config-emoji) basic shows the correct emojis 3`] = `
-"# Description for no-bar (\`test/no-bar\`)
+"# test/no-bar
 
 💼 This rule is enabled in the following configs: 🔥 \`recommended\`, 🎨 \`stylistic\`.
 
+📝 Description for no-bar.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (--config-emoji) basic shows the correct emojis 4`] = `
-"# Description for no-boz (\`test/no-baz\`)
+"# test/no-baz
 
 💼 This rule is enabled in the following configs: 🌟 \`custom\`, 🎨 \`stylistic\`.
 
+📝 Description for no-boz.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -62,10 +68,12 @@ exports[`generate (--config-emoji) with default emoji for common config uses the
 `;
 
 exports[`generate (--config-emoji) with default emoji for common config uses the default emoji when no configEmoji option is provided 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -86,10 +94,12 @@ exports[`generate (--config-emoji) with manually supplied badge markdown uses th
 `;
 
 exports[`generate (--config-emoji) with manually supplied badge markdown uses the badge markdown as provided 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ![fun config badge](https://img.shields.io/badge/-fun-blue.svg) \`funConfig\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/option-config-format-test.ts.snap b/test/lib/generate/__snapshots__/option-config-format-test.ts.snap
index 76f0ffc9..f0b98e45 100644
--- a/test/lib/generate/__snapshots__/option-config-format-test.ts.snap
+++ b/test/lib/generate/__snapshots__/option-config-format-test.ts.snap
@@ -16,10 +16,12 @@ exports[`generate (--config-format) name uses the right format 1`] = `
 `;
 
 exports[`generate (--config-format) name uses the right format 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -40,10 +42,12 @@ exports[`generate (--config-format) plugin-colon-prefix-name uses the right form
 `;
 
 exports[`generate (--config-format) plugin-colon-prefix-name uses the right format 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`plugin:test/recommended\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -64,10 +68,12 @@ exports[`generate (--config-format) prefix-name uses the right format 1`] = `
 `;
 
 exports[`generate (--config-format) prefix-name uses the right format 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`test/recommended\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/option-rule-doc-notices-test.ts.snap b/test/lib/generate/__snapshots__/option-rule-doc-notices-test.ts.snap
index b2f12539..43b5eefc 100644
--- a/test/lib/generate/__snapshots__/option-rule-doc-notices-test.ts.snap
+++ b/test/lib/generate/__snapshots__/option-rule-doc-notices-test.ts.snap
@@ -17,7 +17,7 @@ exports[`generate (--rule-doc-notices) basic shows the right rule doc notices 1`
 `;
 
 exports[`generate (--rule-doc-notices) basic shows the right rule doc notices 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
@@ -25,7 +25,7 @@ exports[`generate (--rule-doc-notices) basic shows the right rule doc notices 2`
 
 ❌ This rule is deprecated.
 
-Description for no-foo.
+📝 Description for no-foo.
 
 ❗ This rule identifies problems that could cause errors or unexpected behavior.
 
diff --git a/test/lib/generate/__snapshots__/option-rule-doc-title-format-test.ts.snap b/test/lib/generate/__snapshots__/option-rule-doc-title-format-test.ts.snap
index 0e84731c..d6114063 100644
--- a/test/lib/generate/__snapshots__/option-rule-doc-title-format-test.ts.snap
+++ b/test/lib/generate/__snapshots__/option-rule-doc-title-format-test.ts.snap
@@ -3,6 +3,8 @@
 exports[`generate (--rule-doc-title-format) desc uses the right rule doc title format 1`] = `
 "# Description for no-foo
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -17,6 +19,8 @@ exports[`generate (--rule-doc-title-format) desc uses the right rule doc title f
 exports[`generate (--rule-doc-title-format) desc-parens-name uses the right rule doc title format 1`] = `
 "# Description for no-foo (\`no-foo\`)
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -31,6 +35,8 @@ exports[`generate (--rule-doc-title-format) desc-parens-name uses the right rule
 exports[`generate (--rule-doc-title-format) desc-parens-prefix-name uses the right rule doc title format, with fallback when missing description 1`] = `
 "# Description for no-foo (\`test/no-foo\`)
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -45,6 +51,8 @@ exports[`generate (--rule-doc-title-format) desc-parens-prefix-name uses the rig
 exports[`generate (--rule-doc-title-format) name uses the right rule doc title format 1`] = `
 "# no-foo
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -52,6 +60,8 @@ exports[`generate (--rule-doc-title-format) name uses the right rule doc title f
 exports[`generate (--rule-doc-title-format) prefix-name uses the right rule doc title format 1`] = `
 "# test/no-foo
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/option-rule-list-columns-test.ts.snap b/test/lib/generate/__snapshots__/option-rule-list-columns-test.ts.snap
index d6b8850b..6084c926 100644
--- a/test/lib/generate/__snapshots__/option-rule-list-columns-test.ts.snap
+++ b/test/lib/generate/__snapshots__/option-rule-list-columns-test.ts.snap
@@ -16,12 +16,14 @@ exports[`generate (--rule-list-columns) basic shows the right columns and legend
 `;
 
 exports[`generate (--rule-list-columns) basic shows the right columns and legend 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated.
 
 🔧💡 This rule is automatically fixable by the [\`--fix\` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix) and manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -59,19 +61,23 @@ exports[`generate (--rule-list-columns) shows column and notice for requiresType
 `;
 
 exports[`generate (--rule-list-columns) shows column and notice for requiresTypeChecking updates the documentation 2`] = `
-"# Description of no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the 🌐 \`all\` config.
 
+📝 Description of no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (--rule-list-columns) shows column and notice for requiresTypeChecking updates the documentation 3`] = `
-"# Description of no-bar (\`test/no-bar\`)
+"# test/no-bar
 
 💭 This rule requires [type information](https://typescript-eslint.io/linting/typed-linting).
 
+📝 Description of no-bar.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/option-url-configs-test.ts.snap b/test/lib/generate/__snapshots__/option-url-configs-test.ts.snap
index 3d64a7ef..8cc58f11 100644
--- a/test/lib/generate/__snapshots__/option-url-configs-test.ts.snap
+++ b/test/lib/generate/__snapshots__/option-url-configs-test.ts.snap
@@ -18,19 +18,23 @@ exports[`generate (--url-configs) basic includes the config link 1`] = `
 `;
 
 exports[`generate (--url-configs) basic includes the config link 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the 🔥 \`recommended\` [config](https://example.com/configs).
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (--url-configs) basic includes the config link 3`] = `
-"# Description for no-bar (\`test/no-bar\`)
+"# test/no-bar
 
 💼 This rule is enabled in the ⭐ \`customConfig\` [config](https://example.com/configs).
 
+📝 Description for no-bar.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -51,10 +55,12 @@ exports[`generate (--url-configs) with only recommended config includes the conf
 `;
 
 exports[`generate (--url-configs) with only recommended config includes the config link 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` [config](https://example.com/configs).
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/option-url-rule-doc-test.ts.snap b/test/lib/generate/__snapshots__/option-url-rule-doc-test.ts.snap
index 0242db23..4e7af0bc 100644
--- a/test/lib/generate/__snapshots__/option-url-rule-doc-test.ts.snap
+++ b/test/lib/generate/__snapshots__/option-url-rule-doc-test.ts.snap
@@ -16,16 +16,20 @@ exports[`generate (--url-rule-doc) basic uses the right URLs 1`] = `
 `;
 
 exports[`generate (--url-rule-doc) basic uses the right URLs 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated. It was replaced by [\`test/no-bar\`](https://example.com/rule-docs/no-bar/).
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (--url-rule-doc) basic uses the right URLs 3`] = `
-"# Description for no-bar (\`test/no-bar\`)
+"# test/no-bar
+
+📝 Description for no-bar.
 
 <!-- end auto-generated rule header -->
 "
@@ -62,16 +66,20 @@ exports[`generate (--url-rule-doc) function returns undefined should fallback to
 `;
 
 exports[`generate (--url-rule-doc) function returns undefined should fallback to the normal URL 3`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated. It was replaced by [\`test/no-bar\`](no-bar.md).
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (--url-rule-doc) function returns undefined should fallback to the normal URL 4`] = `
-"# Description for no-bar (\`test/no-bar\`)
+"# test/no-bar
+
+📝 Description for no-bar.
 
 <!-- end auto-generated rule header -->
 "
@@ -108,16 +116,20 @@ exports[`generate (--url-rule-doc) function uses the custom URL 2`] = `
 `;
 
 exports[`generate (--url-rule-doc) function uses the custom URL 3`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated. It was replaced by [\`test/no-bar\`](https://example.com/rule-docs/name:no-bar/path:docs/rules/no-foo.md).
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (--url-rule-doc) function uses the custom URL 4`] = `
-"# Description for no-bar (\`test/no-bar\`)
+"# test/no-bar
+
+📝 Description for no-bar.
 
 <!-- end auto-generated rule header -->
 "
diff --git a/test/lib/generate/__snapshots__/package-json-test.ts.snap b/test/lib/generate/__snapshots__/package-json-test.ts.snap
index dc038ab9..dfc88b09 100644
--- a/test/lib/generate/__snapshots__/package-json-test.ts.snap
+++ b/test/lib/generate/__snapshots__/package-json-test.ts.snap
@@ -15,7 +15,9 @@ exports[`generate (package.json) No configs found omits the config column 1`] =
 `;
 
 exports[`generate (package.json) No configs found omits the config column 2`] = `
-"# Disallow foo (\`test/no-foo\`)
+"# test/no-foo
+
+📝 Disallow foo.
 
 <!-- end auto-generated rule header -->
 "
@@ -24,10 +26,12 @@ exports[`generate (package.json) No configs found omits the config column 2`] =
 exports[`generate (package.json) No exported rules object found throws an error 1`] = `"Could not find exported \`rules\` object in ESLint plugin."`;
 
 exports[`generate (package.json) Scoped plugin name determines the correct plugin prefix 1`] = `
-"# Disallow foo (\`@my-scope/no-foo\`)
+"# @my-scope/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Disallow foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -46,10 +50,12 @@ exports[`generate (package.json) Scoped plugin with custom plugin name determine
 `;
 
 exports[`generate (package.json) Scoped plugin with custom plugin name determines the correct plugin prefix 2`] = `
-"# Disallow foo (\`@my-scope/foo/no-foo\`)
+"# @my-scope/foo/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Disallow foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -68,10 +74,12 @@ exports[`generate (package.json) plugin entry point in JSON format generates the
 `;
 
 exports[`generate (package.json) plugin entry point in JSON format generates the documentation 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
 
 💼 This rule is enabled in the ✅ \`recommended\` config.
 
+📝 Description for no-foo.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/rule-deprecation-test.ts.snap b/test/lib/generate/__snapshots__/rule-deprecation-test.ts.snap
index ec1da1b1..f68218ea 100644
--- a/test/lib/generate/__snapshots__/rule-deprecation-test.ts.snap
+++ b/test/lib/generate/__snapshots__/rule-deprecation-test.ts.snap
@@ -13,10 +13,12 @@ exports[`generate (deprecated rules) replaced by ESLint core rule uses correct r
 `;
 
 exports[`generate (deprecated rules) replaced by ESLint core rule uses correct replacement rule link 2`] = `
-"# Description (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated. It was replaced by [\`no-unused-vars\`](https://eslint.org/docs/latest/rules/no-unused-vars).
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -34,10 +36,12 @@ exports[`generate (deprecated rules) replaced by third-party plugin rule uses co
 `;
 
 exports[`generate (deprecated rules) replaced by third-party plugin rule uses correct replacement rule link 2`] = `
-"# Description (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated. It was replaced by \`other-plugin/no-unused-vars\`.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -55,10 +59,12 @@ exports[`generate (deprecated rules) replaced by third-party plugin rule with sa
 `;
 
 exports[`generate (deprecated rules) replaced by third-party plugin rule with same rule name as one of our rules uses correct replacement rule link 2`] = `
-"# Description (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated. It was replaced by \`other-plugin/no-foo\`.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -80,44 +86,54 @@ exports[`generate (deprecated rules) several deprecated rules updates the docume
 `;
 
 exports[`generate (deprecated rules) several deprecated rules updates the documentation 2`] = `
-"# Description (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated. It was replaced by [\`test/no-bar\`](no-bar.md).
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (deprecated rules) several deprecated rules updates the documentation 3`] = `
-"# Description (\`test/no-bar\`)
+"# test/no-bar
 
 ❌ This rule is deprecated.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (deprecated rules) several deprecated rules updates the documentation 4`] = `
-"# Description (\`test/no-baz\`)
+"# test/no-baz
 
 ❌ This rule is deprecated.
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (deprecated rules) several deprecated rules updates the documentation 5`] = `
-"# Description (\`test/no-biz\`)
+"# test/no-biz
+
+📝 Description.
 
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (deprecated rules) several deprecated rules updates the documentation 6`] = `
-"# Description (\`test/no-boz\`)
+"# test/no-boz
 
 ❌ This rule is deprecated. It was replaced by [\`test/no-baz\`](no-baz.md), [\`test/no-biz\`](no-biz.md).
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -136,16 +152,20 @@ exports[`generate (deprecated rules) using prefix ahead of replacement rule name
 `;
 
 exports[`generate (deprecated rules) using prefix ahead of replacement rule name uses correct replacement rule link 2`] = `
-"# Description (\`test/no-foo\`)
+"# test/no-foo
 
 ❌ This rule is deprecated. It was replaced by [\`test/no-bar\`](no-bar.md).
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (deprecated rules) using prefix ahead of replacement rule name uses correct replacement rule link 3`] = `
-"# Description (\`test/no-bar\`)
+"# test/no-bar
+
+📝 Description.
 
 <!-- end auto-generated rule header -->
 "
@@ -165,19 +185,23 @@ exports[`generate (deprecated rules) with --path-rule-doc has the correct links,
 `;
 
 exports[`generate (deprecated rules) with --path-rule-doc has the correct links, especially replacement rule link 2`] = `
-"# Description (\`test/category/no-foo\`)
+"# test/category/no-foo
 
 ❌ This rule is deprecated. It was replaced by [\`test/category/no-bar\`](../no-bar/README.md).
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (deprecated rules) with --path-rule-doc has the correct links, especially replacement rule link 3`] = `
-"# Description (\`test/category/no-bar\`)
+"# test/category/no-bar
 
 ❌ This rule is deprecated. It was replaced by [\`test/category/no-foo\`](../no-foo/README.md).
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
@@ -196,19 +220,23 @@ exports[`generate (deprecated rules) with nested rule names has the correct link
 `;
 
 exports[`generate (deprecated rules) with nested rule names has the correct links, especially replacement rule link 2`] = `
-"# Description (\`test/category/no-foo\`)
+"# test/category/no-foo
 
 ❌ This rule is deprecated. It was replaced by [\`test/category/no-bar\`](no-bar.md).
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
 
 exports[`generate (deprecated rules) with nested rule names has the correct links, especially replacement rule link 3`] = `
-"# Description (\`test/category/no-bar\`)
+"# test/category/no-bar
 
 ❌ This rule is deprecated. It was replaced by [\`test/category/no-foo\`](no-foo.md).
 
+📝 Description.
+
 <!-- end auto-generated rule header -->
 "
 `;
diff --git a/test/lib/generate/__snapshots__/rule-description-test.ts.snap b/test/lib/generate/__snapshots__/rule-description-test.ts.snap
index c0244e4d..ebd84e7a 100644
--- a/test/lib/generate/__snapshots__/rule-description-test.ts.snap
+++ b/test/lib/generate/__snapshots__/rule-description-test.ts.snap
@@ -1,7 +1,9 @@
 // Jest Snapshot v1, https://goo.gl/fbAQLP
 
 exports[`generate (rule descriptions) Rule description needs to be formatted capitalizes the first letter and removes the trailing period from the description 1`] = `
-"# Disallow foo (\`test/no-foo\`)
+"# test/no-foo
+
+📝 Disallow foo.
 
 <!-- end auto-generated rule header -->
 "
@@ -40,7 +42,9 @@ exports[`generate (rule descriptions) one rule missing description generates the
 `;
 
 exports[`generate (rule descriptions) one rule missing description generates the documentation 2`] = `
-"# Description for no-foo (\`test/no-foo\`)
+"# test/no-foo
+
+📝 Description for no-foo.
 
 <!-- end auto-generated rule header -->
 "
@@ -66,7 +70,9 @@ exports[`generate (rule descriptions) rule with long-enough description to requi
 `;
 
 exports[`generate (rule descriptions) rule with long-enough description to require name column wrapping avoidance adds spaces to the name column 2`] = `
-"# Over 60 chars over 60 chars over 60 chars over 60 chars over 60 chars over 60 chars (\`test/no-foo\`)
+"# test/no-foo
+
+📝 Over 60 chars over 60 chars over 60 chars over 60 chars over 60 chars over 60 chars.
 
 <!-- end auto-generated rule header -->
 "
@@ -85,7 +91,9 @@ exports[`generate (rule descriptions) rule with long-enough description to requi
 `;
 
 exports[`generate (rule descriptions) rule with long-enough description to require name column wrapping avoidance but rule name too short does not add spaces to name column 2`] = `
-"# Over 60 chars over 60 chars over 60 chars over 60 chars over 60 chars over 60 chars (\`test/foo\`)
+"# test/foo
+
+📝 Over 60 chars over 60 chars over 60 chars over 60 chars over 60 chars over 60 chars.
 
 <!-- end auto-generated rule header -->
 "

From e1fea88d7fe87f923f1fe04470a35238e4fe3fa2 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Thu, 1 Jan 2026 15:21:44 -0500
Subject: [PATCH 2/5] wip

---
 lib/options.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/lib/options.ts b/lib/options.ts
index ba1adf9c..df01fea7 100644
--- a/lib/options.ts
+++ b/lib/options.ts
@@ -38,8 +38,8 @@ export const NOTICE_TYPE_DEFAULT_PRESENCE_AND_ORDERING: {
 } = {
   // Object keys ordered in display order.
   // Object values indicate whether the column is displayed by default.
-  [NOTICE_TYPE.CONFIGS]: true,
   [NOTICE_TYPE.DEPRECATED]: true, // Most important.
+  [NOTICE_TYPE.CONFIGS]: true,
   [NOTICE_TYPE.FIXABLE]: false,
   [NOTICE_TYPE.FIXABLE_AND_HAS_SUGGESTIONS]: true, // Default, consolidated notice.
   [NOTICE_TYPE.HAS_SUGGESTIONS]: false,

From 469d12c21c9a07e2546d563e878d34db7c599f60 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Thu, 1 Jan 2026 15:23:35 -0500
Subject: [PATCH 3/5] wip

---
 test/fixtures/cjs-config-extends/README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/test/fixtures/cjs-config-extends/README.md b/test/fixtures/cjs-config-extends/README.md
index 83499ecb..95c16095 100644
--- a/test/fixtures/cjs-config-extends/README.md
+++ b/test/fixtures/cjs-config-extends/README.md
@@ -9,9 +9,9 @@
 
 | Name                           | Description            | 💼 |
 | :----------------------------- | :--------------------- | :- |
-| [no-bar](docs/rules/no-bar.md) | Description of no-bar. | ✅  |
-| [no-baz](docs/rules/no-baz.md) | Description of no-baz. | ✅  |
-| [no-biz](docs/rules/no-biz.md) | Description of no-biz. | ✅  |
-| [no-foo](docs/rules/no-foo.md) | Description of no-foo. | ✅  |
+| [no-bar](docs/rules/no-bar.md) | Description of no-bar. | ✅ |
+| [no-baz](docs/rules/no-baz.md) | Description of no-baz. | ✅ |
+| [no-biz](docs/rules/no-biz.md) | Description of no-biz. | ✅ |
+| [no-foo](docs/rules/no-foo.md) | Description of no-foo. | ✅ |
 
 <!-- end auto-generated rules list -->

From 0f0127c35623cea86d2e47fdb03ab431434c3f70 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Thu, 1 Jan 2026 15:35:52 -0500
Subject: [PATCH 4/5] wip

---
 .../eslint-plugin-test/docs/rules/no-foo.md   |  4 +++-
 .../docs/rules/prefer-bar.md                  |  4 +++-
 .../docs/rules/require-baz.md                 |  4 +++-
 test/fixtures/cjs-config-extends/README.md    |  8 ++++----
 .../generate/__snapshots__/cjs-test.ts.snap   | 20 ++++++++++++++-----
 5 files changed, 28 insertions(+), 12 deletions(-)

diff --git a/docs/examples/eslint-plugin-test/docs/rules/no-foo.md b/docs/examples/eslint-plugin-test/docs/rules/no-foo.md
index 82112b5c..377621cf 100644
--- 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
index cbff8557..3e453805 100644
--- 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
index c28bc4c4..12c7a65b 100644
--- 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/test/fixtures/cjs-config-extends/README.md b/test/fixtures/cjs-config-extends/README.md
index 95c16095..83499ecb 100644
--- a/test/fixtures/cjs-config-extends/README.md
+++ b/test/fixtures/cjs-config-extends/README.md
@@ -9,9 +9,9 @@
 
 | Name                           | Description            | 💼 |
 | :----------------------------- | :--------------------- | :- |
-| [no-bar](docs/rules/no-bar.md) | Description of no-bar. | ✅ |
-| [no-baz](docs/rules/no-baz.md) | Description of no-baz. | ✅ |
-| [no-biz](docs/rules/no-biz.md) | Description of no-biz. | ✅ |
-| [no-foo](docs/rules/no-foo.md) | Description of no-foo. | ✅ |
+| [no-bar](docs/rules/no-bar.md) | Description of no-bar. | ✅  |
+| [no-baz](docs/rules/no-baz.md) | Description of no-baz. | ✅  |
+| [no-biz](docs/rules/no-biz.md) | Description of no-biz. | ✅  |
+| [no-foo](docs/rules/no-foo.md) | Description of no-foo. | ✅  |
 
 <!-- end auto-generated rules list -->
diff --git a/test/lib/generate/__snapshots__/cjs-test.ts.snap b/test/lib/generate/__snapshots__/cjs-test.ts.snap
index 09ebf7f6..febef1bf 100644
--- 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 -->
 "
 `;

From 73a781a3b21c00f75b1139c1b61449f241d4c4c1 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Thu, 1 Jan 2026 15:37:12 -0500
Subject: [PATCH 5/5] wip

---
 test/fixtures/cjs-config-extends/README.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/test/fixtures/cjs-config-extends/README.md b/test/fixtures/cjs-config-extends/README.md
index 83499ecb..95c16095 100644
--- a/test/fixtures/cjs-config-extends/README.md
+++ b/test/fixtures/cjs-config-extends/README.md
@@ -9,9 +9,9 @@
 
 | Name                           | Description            | 💼 |
 | :----------------------------- | :--------------------- | :- |
-| [no-bar](docs/rules/no-bar.md) | Description of no-bar. | ✅  |
-| [no-baz](docs/rules/no-baz.md) | Description of no-baz. | ✅  |
-| [no-biz](docs/rules/no-biz.md) | Description of no-biz. | ✅  |
-| [no-foo](docs/rules/no-foo.md) | Description of no-foo. | ✅  |
+| [no-bar](docs/rules/no-bar.md) | Description of no-bar. | ✅ |
+| [no-baz](docs/rules/no-baz.md) | Description of no-baz. | ✅ |
+| [no-biz](docs/rules/no-biz.md) | Description of no-biz. | ✅ |
+| [no-foo](docs/rules/no-foo.md) | Description of no-foo. | ✅ |
 
 <!-- end auto-generated rules list -->