From b86565446cc99fe13524261bfb8092aaf5820ea4 Mon Sep 17 00:00:00 2001
From: Bryan Mishkin <698306+bmish@users.noreply.github.com>
Date: Sun, 5 Nov 2023 10:51:56 -0500
Subject: [PATCH] docs: deprecate badges defined in READMEs

---
 README.md    | 12 +++++-------
 lib/cli.ts   |  2 +-
 lib/types.ts |  2 +-
 3 files changed, 7 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 2be18879..5e92ee1d 100644
--- a/README.md
+++ b/README.md
@@ -177,7 +177,7 @@ There's also a `postprocess` option that's only available via a [config file](#c
 | Name | Description | Default |
 | :-- | :-- | :-- |
 | `--check` | Whether to check for and fail if there is a diff. Any diff will be displayed but no output will be written to files. Typically used during CI. | `false` |
-| `--config-emoji` | Custom emoji to use for a config. Format is `config-name,emoji`. Option can be repeated. | Default emojis are provided for [common configs](./lib/emojis.ts). To remove a default emoji and rely on a [badge](#badges) instead, provide the config name without an emoji. |
+| `--config-emoji` | Custom emoji to use for a config. Format is `config-name,emoji`. Option can be repeated. | Default emojis are provided for [common configs](./lib/emojis.ts). See [Badges](#badges) for an alternative to emojis. |
 | `--config-format` | The format to use for config names. See choices in below [table](#--config-format). | `name` |
 | `--ignore-config` | Config to ignore from being displayed. Often used for an `all` config. Option can be repeated. | |
 | `--ignore-deprecated-rules` | Whether to ignore deprecated rules from being checked, displayed, or updated. | `false` |
@@ -305,19 +305,17 @@ module.exports = config;
 
 ### Badges
 
-While config emojis are the recommended representations of configs that a rule belongs to (see [`--config-emoji`](#configuration-options)), you can alternatively define badges for configs at the bottom of your `README.md`.
+While emojis are the recommended representations of configs that a rule belongs to, you can alternatively use a text/image/icon badge for configs by supplying the following markdown for the emoji using the [`--config-emoji`](#configuration-options) option.
 
-Here's a badge for a custom `fun` config that displays in blue:
+For example, here's the markdown for text badge representing a custom `fun` config that displays in blue (note that the markdown includes alt text followed by the image URL):
 
 ```md
-[badge-fun]: https://img.shields.io/badge/-fun-blue.svg
+![fun config badge](https://img.shields.io/badge/-fun-blue.svg)
 ```
 
 And how it looks:
 
-![badge-fun][]
-
-[badge-fun]: https://img.shields.io/badge/-fun-blue.svg
+![fun config badge](https://img.shields.io/badge/-fun-blue.svg)
 
 ## Compatibility
 
diff --git a/lib/cli.ts b/lib/cli.ts
index 86cc3d29..71e798e0 100644
--- a/lib/cli.ts
+++ b/lib/cli.ts
@@ -192,7 +192,7 @@ export async function run(
     )
     .option(
       '--config-emoji <config-emoji>',
-      '(optional) Custom emoji to use for a config. Format is `config-name,emoji`. Default emojis are provided for common configs. To remove a default emoji and rely on a badge instead, provide the config name without an emoji. Option can be repeated.',
+      '(optional) Custom emoji to use for a config. Format is `config-name,emoji`. Default emojis are provided for common configs. To use a text/image/icon badge instead of an emoji, supply the corresponding markdown as the emoji. Option can be repeated.',
       collectCSVNested,
       []
     )
diff --git a/lib/types.ts b/lib/types.ts
index a9e28707..0c0e574d 100644
--- a/lib/types.ts
+++ b/lib/types.ts
@@ -152,7 +152,7 @@ export type GenerateOptions = {
    * List of configs and their associated emojis.
    * Array of `[configName, emoji]`.
    * Default emojis are provided for common configs.
-   * To remove a default emoji and rely on a badge instead, provide the config name without an emoji.
+   * To use a text/image/icon badge instead of an emoji, supply the corresponding markdown as the emoji.
    */
   readonly configEmoji?: readonly (
     | [configName: string, emoji: string]