From 3aec1c55ba2c6d2833e1c0afe0a58f0cc6bbc0a4 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Josh=20Goldberg=20=E2=9C=A8?= <git@joshuakgoldberg.com>
Date: Tue, 24 Oct 2023 11:31:34 -0400
Subject: [PATCH] docs: explained rule fixers and suggestions (#17657)

* docs: explained report fixers and suggestions

* Apply suggestions from code review

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>

* Post-suggestion fix: rule-categories.macro.html link

---------

Co-authored-by: Nicholas C. Zakas <nicholas@humanwhocodes.com>
---
 .../components/rule-categories.macro.html       |  2 +-
 docs/src/use/core-concepts.md                   | 17 +++++++++++++++++
 2 files changed, 18 insertions(+), 1 deletion(-)

diff --git a/docs/src/_includes/components/rule-categories.macro.html b/docs/src/_includes/components/rule-categories.macro.html
index 193f6def64e..f38d371049e 100644
--- a/docs/src/_includes/components/rule-categories.macro.html
+++ b/docs/src/_includes/components/rule-categories.macro.html
@@ -21,7 +21,7 @@
     <div class="rule-category">
         <span class="rule-category__icon">💡 <span class="visually-hidden">hasSuggestions</span></span>
         <p class="rule-category__description">
-            Some problems reported by this rule are manually fixable by editor <a href="../extend/custom-rules#providing-suggestions">suggestions</a>
+            Some problems reported by this rule are manually fixable by editor <a href="../use/core-concepts#rule-suggestions">suggestions</a>
         </p>
     </div>
     {%- endif -%}
diff --git a/docs/src/use/core-concepts.md b/docs/src/use/core-concepts.md
index b9dfbbbfa1c..b60ad3b0b0e 100644
--- a/docs/src/use/core-concepts.md
+++ b/docs/src/use/core-concepts.md
@@ -23,6 +23,23 @@ ESLint contains hundreds of built-in rules that you can use. You can also create
 
 For more information, refer to [Rules](../rules/).
 
+### Rule Fixes
+
+Rules may optionally provide fixes for violations that they find. Fixes safely correct the violation without changing application logic.
+
+Fixes may be applied automatically with the [`--fix` command line option](https://eslint.org/docs/latest/use/command-line-interface#--fix) and via editor extensions.
+
+Rules that may provide fixes are marked with 🔧 in [Rules](../rules/).
+
+### Rule Suggestions
+
+Rules may optionally provide suggestions in addition to or instead of providing fixes. Suggestions differ from fixes in two ways:
+
+1. Suggestions may change application logic and so cannot be automatically applied.
+1. Suggestions cannot be applied through the ESLint CLI and are only available through editor integrations.
+
+Rules that may provide suggestions are marked with 💡 in [Rules](../rules/).
+
 ## Configuration Files
 
 An ESLint configuration file is a place where you put the configuration for ESLint in your project. You can include built-in rules, how you want them enforced, plugins with custom rules, shareable configurations, which files you want rules to apply to, and more.