Use special alerts in GitHub Markdown (#7293)

GitHub provides more rich UI for alerts in Markdown files (beta). This is similar to Docusaurus Admonitions (which is used in stylelint.io), and should improve our documentation readability. See: - https://github.com/orgs/community/discussions/16925 - https://docusaurus.io/docs/markdown-features/admonitions - https://github.com/stylelint/stylelint.io/pull/357/files#r1378999753
stylelint · Nov 2, 2023 · 0f74d1e · 0f74d1e
1 parent b6f8ab6
commit 0f74d1e
Show file tree

Hide file tree

Showing 12 changed files with 43 additions and 17 deletions.
diff --git a/docs/user-guide/configure.md b/docs/user-guide/configure.md
@@ -480,7 +480,8 @@ If the globs are absolute paths, they are used as is. If they are relative, they
 - the config's filepath, if the config is a file that Stylelint found and loaded;
 - or `process.cwd()`.
 
-_Note that this is not an efficient method for ignoring lots of files._ If you want to ignore a lot of files efficiently, use [`.stylelintignore`](ignore-code.md) or adjust your files globs.
+> [!NOTE]
+> This is **not an efficient method for ignoring lots of files**. If you want to ignore a lot of files efficiently, use [`.stylelintignore`](ignore-code.md) or adjust your files globs.
 
 ## `allowEmptyInput`
 
@@ -494,7 +495,8 @@ For example:
 }
 ```
 
-Note: this config option should not be overridden on a per-file basis.
+> [!NOTE]
+> This config option should not be overridden on a per-file basis.
 
 [More info](options.md#allowemptyinput).
 
@@ -510,7 +512,8 @@ For example:
 }
 ```
 
-Note: this config option should not be overridden on a per-file basis.
+> [!NOTE]
+> This config option should not be overridden on a per-file basis.
 
 [More info](options.md#cache).
 
@@ -526,6 +529,7 @@ For example:
 }
 ```
 
-Note: this config option should not be overridden on a per-file basis.
+> [!NOTE]
+> This config option should not be overridden on a per-file basis.
 
 [More info](options.md#fix).
diff --git a/docs/user-guide/ignore-code.md b/docs/user-guide/ignore-code.md
@@ -62,7 +62,8 @@ Stylelint supports complex, overlapping disabling & enabling patterns:
 /* stylelint-enable foo */
 ```
 
-**Caveat:** Comments within _selector and value lists_ are currently ignored.
+> [!WARNING]
+> Comments within _selector and value lists_ are currently ignored.
 
 You may also include a description at the end of the comment, after two hyphens:
 
@@ -72,7 +73,8 @@ You may also include a description at the end of the comment, after two hyphens:
 /* stylelint-disable foo, bar -- Reason for disabling the foo and bar rules. */
 ```
 
-**Important:** There must be a space on both sides of the hyphens.
+> [!WARNING]
+> There must be a space on both sides of the hyphens.
 
 ## Files entirely
 

diff --git a/docs/user-guide/node-api.md b/docs/user-guide/node-api.md
@@ -60,7 +60,8 @@ Boolean. If `true`, at least one rule with an "error"-level severity registered
 
 ### `output`
 
-> **Warning** This property is deprecated and will be removed in the next major version. Use [`report`](#report) or [`code`](#code-1) instead. See [the migration guide](../migration-guide/to-16.md).
+> [!WARNING]
+> This property is deprecated and will be removed in the next major version. Use [`report`](#report) or [`code`](#code-1) instead. See [the migration guide](../migration-guide/to-16.md).
 
 A string that contains either the:
 
@@ -183,7 +184,8 @@ stylelint
   });
 ```
 
-Note that the customSyntax option also accepts a string. [Refer to the options documentation for details](./options.md#customsyntax).
+> [!NOTE]
+> The `customSyntax` option also accepts a string. [Refer to the options documentation for details](./options.md#customsyntax).
 
 ### Example F
 

diff --git a/docs/user-guide/options.md b/docs/user-guide/options.md
@@ -72,7 +72,8 @@ If you want to lint two or more different languages, you can combine `customSynt
 
 Using the Node.js API, the `customSyntax` option can also accept a [Syntax object](https://github.com/postcss/postcss/blob/abfaa7122a0f480bc5be0905df3c24a6a51a82d9/lib/postcss.d.ts#L223-L232). Stylelint treats the `parse` property as a required value.
 
-Note that Stylelint can provide no guarantee that core rules work with custom syntaxes.
+> [!NOTE]
+> Stylelint can provide no guarantee that core rules work with custom syntaxes.
 
 ## `formatter`
 

diff --git a/lib/rules/comment-no-empty/README.md b/lib/rules/comment-no-empty/README.md
@@ -11,7 +11,8 @@ Disallow empty comments.
 
 This rule ignores SCSS-like comments.
 
-**Caveat:** Comments within _selector and value lists_ are currently ignored.
+> [!WARNING]
+> Comments within _selector and value lists_ are currently ignored.
 
 ## Options
 

diff --git a/lib/rules/comment-whitespace-inside/README.md b/lib/rules/comment-whitespace-inside/README.md
@@ -11,7 +11,8 @@ Require or disallow whitespace on the inside of comment markers.
 
 Any number of asterisks are allowed at the beginning or end of the comment. So `/** comment **/` is treated the same way as `/* comment */`.
 
-**Caveat:** Comments within _selector and value lists_ are currently ignored.
+> [!WARNING]
+> Comments within _selector and value lists_ are currently ignored.
 
 The [`fix` option](../../../docs/user-guide/options.md#fix) can automatically fix all of the problems reported by this rule.
 

diff --git a/lib/rules/comment-word-disallowed-list/README.md b/lib/rules/comment-word-disallowed-list/README.md
@@ -9,7 +9,8 @@ Specify a list of disallowed words within comments.
  * These three words */
 ```
 
-**Caveat:** Comments within _selector and value lists_ are currently ignored.
+> [!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.
 

diff --git a/lib/rules/declaration-block-no-redundant-longhand-properties/README.md b/lib/rules/declaration-block-no-redundant-longhand-properties/README.md
@@ -84,7 +84,8 @@ This rule complains when the following shorthand properties can be used:
 - `text-emphasis`
 - `transition`
 
-**Please note** that properties are considered to be redundant if they may be written shorthand according to the specification, **regardless of the behavior of any individual browser**. For example, due to Internet Explorer's implementation of Flexbox, [it may not be possible to use the shorthand property `flex`](https://github.com/philipwalton/flexbugs#flexbug-8), but the longhand form is still considered a problem.
+> [!WARNING]
+> Please note that properties are considered to be redundant if they may be written shorthand according to the specification, **regardless of the behavior of any individual browser**. For example, due to Internet Explorer's implementation of Flexbox, [it may not be possible to use the shorthand property `flex`](https://github.com/philipwalton/flexbugs#flexbug-8), but the longhand form is still considered a problem.
 
 Flexbox-related properties can be ignored using `ignoreShorthands: ["/flex/"]` (see below).
 

diff --git a/lib/rules/font-family-name-quotes/README.md b/lib/rules/font-family-name-quotes/README.md
@@ -28,7 +28,8 @@ _Please read the following to understand these options_:
 
 For more on these subtleties, read ["Unquoted font family names in CSS"](https://mathiasbynens.be/notes/unquoted-font-family), by Mathias Bynens.
 
-**Caveat:** This rule does not currently understand escape sequences such as those described by Mathias. If you want to use the font family name "Hawaii 5-0" you will need to wrap it in quotes, instead of escaping it as `Hawaii \35 -0` or `Hawaii\ 5-0`.
+> [!WARNING]
+> This rule does not currently understand escape sequences such as those described by Mathias. If you want to use the font family name "Hawaii 5-0" you will need to wrap it in quotes, instead of escaping it as `Hawaii \35 -0` or `Hawaii\ 5-0`.
 
 ### `"always-unless-keyword"`
 

diff --git a/lib/rules/font-family-no-duplicate-names/README.md b/lib/rules/font-family-no-duplicate-names/README.md
@@ -13,7 +13,8 @@ This rule checks the `font` and `font-family` properties.
 
 This rule ignores `$sass`, `@less`, and `var(--custom-property)` variable syntaxes.
 
-**Caveat:** This rule will stumble on _unquoted_ multi-word font names and _unquoted_ font names containing escape sequences. Wrap these font names in quotation marks, and everything should be fine.
+> [!WARNING]
+> This rule will stumble on _unquoted_ multi-word font names and _unquoted_ font names containing escape sequences. Wrap these font names in quotation marks, and everything should be fine.
 
 ## Options
 

diff --git a/lib/rules/max-nesting-depth/README.md b/lib/rules/max-nesting-depth/README.md
@@ -26,7 +26,8 @@ a {
 }
 ```
 
-Note that **root-level at-rules will _not_ be included in the nesting depth calculation**, because most users would take for granted that root-level at-rules are "free" (because necessary). So both of the following `.foo` rules have a nesting depth of 2, and will therefore pass if your `max` is less than or equal to 2:
+> [!NOTE]
+> root-level at-rules will **not be included** in the nesting depth calculation, because most users would take for granted that root-level at-rules are "free" (because necessary). So both of the following `.foo` rules have a nesting depth of 2, and will therefore pass if your `max` is less than or equal to 2:
 
 <!-- prettier-ignore -->
 ```css

diff --git a/package.json b/package.json
@@ -92,7 +92,17 @@
   },
   "remarkConfig": {
     "plugins": [
-      "@stylelint/remark-preset"
+      "@stylelint/remark-preset",
+      [
+        "remark-lint-no-undefined-references",
+        {
+          "allow": [
+            "!NOTE",
+            "!IMPORTANT",
+            "!WARNING"
+          ]
+        }
+      ]
     ]
   },
   "jest": {