From 127b4fe69fb4500387134ea6a977e4134f533883 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Fri, 15 Aug 2025 21:00:54 +0900 Subject: [PATCH 01/29] feat: support GFM Alert syntax parsing --- designs/2025-support-gfm-alert-syntax-parsing | 104 ++++++++++++++++++ 1 file changed, 104 insertions(+) create mode 100644 designs/2025-support-gfm-alert-syntax-parsing diff --git a/designs/2025-support-gfm-alert-syntax-parsing b/designs/2025-support-gfm-alert-syntax-parsing new file mode 100644 index 00000000..ef65d91a --- /dev/null +++ b/designs/2025-support-gfm-alert-syntax-parsing @@ -0,0 +1,104 @@ +- Repo: eslint/markdown +- Start Date: 2025-08-15 +- RFC PR: TODO +- Authors: 루밀LuMir(lumirlumir) + +# Support GFM Alert syntax parsing + +## Summary + + + +## Motivation + + + +## Detailed Design + + + +## Documentation + + + +## Drawbacks + + + +## Backwards Compatibility Analysis + + + +## Alternatives + + + +## Open Questions + + + +## Help Needed + + + +## Frequently Asked Questions + + + +## Related Discussions + + From 8a54303644960fc724243e5bec100e747183522a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Fri, 15 Aug 2025 21:18:24 +0900 Subject: [PATCH 02/29] Update 2025-support-gfm-alert-syntax-parsing --- designs/2025-support-gfm-alert-syntax-parsing | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing b/designs/2025-support-gfm-alert-syntax-parsing index ef65d91a..cd4d2f56 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing +++ b/designs/2025-support-gfm-alert-syntax-parsing @@ -7,7 +7,7 @@ ## Summary - +This RFC proposes adding support for GFM Alert syntax parsing to the `@eslint/markdown` package by implementing custom [`micromark-extension-gfm-alert`](https://github.com/micromark/micromark-extension-gfm?tab=readme-ov-file#when-to-use-this) and [`mdast-util-gfm-alert`](https://github.com/syntax-tree/mdast-util-gfm?tab=readme-ov-file#when-to-use-this) logic, and also includes the formal specification based on the [CommonMark spec](https://spec.commonmark.org/) and the [GitHub Flavored Markdown spec](https://github.github.com/gfm/). ## Motivation From e3ccf5c330b1bb0cd63e87dfa42830d1c8aa3588 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Fri, 15 Aug 2025 21:24:13 +0900 Subject: [PATCH 03/29] wip --- .../README.md} | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) rename designs/{2025-support-gfm-alert-syntax-parsing => 2025-support-gfm-alert-syntax-parsing/README.md} (98%) diff --git a/designs/2025-support-gfm-alert-syntax-parsing b/designs/2025-support-gfm-alert-syntax-parsing/README.md similarity index 98% rename from designs/2025-support-gfm-alert-syntax-parsing rename to designs/2025-support-gfm-alert-syntax-parsing/README.md index cd4d2f56..31067cba 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -1,6 +1,6 @@ - Repo: eslint/markdown - Start Date: 2025-08-15 -- RFC PR: TODO +- RFC PR: https://github.com/eslint/rfcs/pull/138 - Authors: 루밀LuMir(lumirlumir) # Support GFM Alert syntax parsing From 925487c9dc3ac8c5035dd46fb78dda159d96ba39 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Fri, 15 Aug 2025 21:34:53 +0900 Subject: [PATCH 04/29] wip --- .../README.md | 46 +++++++++++++++++-- 1 file changed, 43 insertions(+), 3 deletions(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 31067cba..fbb7728e 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -7,12 +7,52 @@ ## Summary -This RFC proposes adding support for GFM Alert syntax parsing to the `@eslint/markdown` package by implementing custom [`micromark-extension-gfm-alert`](https://github.com/micromark/micromark-extension-gfm?tab=readme-ov-file#when-to-use-this) and [`mdast-util-gfm-alert`](https://github.com/syntax-tree/mdast-util-gfm?tab=readme-ov-file#when-to-use-this) logic, and also includes the formal specification based on the [CommonMark spec](https://spec.commonmark.org/) and the [GitHub Flavored Markdown spec](https://github.github.com/gfm/). +This RFC proposes adding support for GFM Alert syntax parsing to the `@eslint/markdown` package by implementing custom `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` logic, and also includes the formal specification based on the [CommonMark spec](https://spec.commonmark.org/) and the [GitHub Flavored Markdown spec](https://github.github.com/gfm/). ## Motivation - +The motivation for this RFC comes from [eslint/markdown#294](https://github.com/eslint/markdown/issues/294) and [eslint/markdown#449](https://github.com/eslint/markdown/issues/449). + +Currently, GitHub supports a special syntax for alerts that isn't mentioned in the [GitHub Flavored Markdown spec](https://github.github.com/gfm/) and isn't parsed by the existing [`micromark-extension-gfm`](https://github.com/micromark/micromark-extension-gfm?tab=readme-ov-file#when-to-use-this) or [`mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm?tab=readme-ov-file#when-to-use-this) packages, which are used internally by `@eslint/markdown` to parse Markdown content and create AST nodes. + +This RFC aims to address that gap by introducing the necessary parsing logic and formal specification for GFM Alert syntax. + +GFM Alert syntax is a way to create attention-grabbing blocks in Markdown content. It uses a specific syntax to denote different types of alerts, such as notes, tips, warnings, and more. The basic structure of a GFM Alert is as follows: + +```md +> [!NOTE] +> Useful information that users should know, even when skimming content. + +> [!TIP] +> Helpful advice for doing things better or more easily. + +> [!IMPORTANT] +> Key information users need to know to achieve their goal. + +> [!WARNING] +> Urgent info that needs immediate user attention to avoid problems. + +> [!CAUTION] +> Advises about risks or negative outcomes of certain actions. +``` + +Which is being rendered on GitHub as: + +> [!NOTE] +> Useful information that users should know, even when skimming content. + +> [!TIP] +> Helpful advice for doing things better or more easily. + +> [!IMPORTANT] +> Key information users need to know to achieve their goal. + +> [!WARNING] +> Urgent info that needs immediate user attention to avoid problems. + +> [!CAUTION] +> Advises about risks or negative outcomes of certain actions. + ## Detailed Design From b081509e0e66e20b56edb5316eaa938c418d2a50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Fri, 15 Aug 2025 22:39:58 +0900 Subject: [PATCH 05/29] wip --- .../README.md | 131 ++++++++++++++++++ 1 file changed, 131 insertions(+) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index fbb7728e..858ab38d 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -65,6 +65,130 @@ Which is being rendered on GitHub as: used. Be sure to define any new terms in this section. --> +### Valid Syntax + +#### Labels are case-insensitive + +
+Details + +```md +> [!NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [!NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [!note] +> Useful information that users should know, even when skimming content. +``` + +> [!note] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [!Note] +> Useful information that users should know, even when skimming content. +``` + +> [!Note] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [!NoTe] +> Useful information that users should know, even when skimming content. +``` + +> [!NoTe] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [!nOtE] +> Useful information that users should know, even when skimming content. +``` + +> [!nOtE] +> Useful information that users should know, even when skimming content. + +
+ +### Invalid Syntax + +#### `!` prefix should not be surrounded by any spaces (U+0020) or tabs (U+0009). + +
+Details + +```md +> [ !NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [ !NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [ !NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [ !NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [! NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [! NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [! NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [! NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [ ! NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [ ! NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [ ! NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [ ! NOTE] +> Useful information that users should know, even when skimming content. + +
+ ## Documentation + +- The reasons why GitHub Alert syntax is not included in Mdast: + - https://github.com/syntax-tree/mdast-util-gfm/issues/2 + - https://github.com/orgs/syntax-tree/discussions/144 + +- `rehype-github-alert` library: + - https://github.com/rehypejs/rehype-github/tree/main/packages/alert#rehype-github-alert From 2def681ab7b0511c2f5e5dec7678d0a725359866 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Fri, 15 Aug 2025 22:47:20 +0900 Subject: [PATCH 06/29] wip --- .../README.md | 51 ++++++++++++++----- 1 file changed, 38 insertions(+), 13 deletions(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 858ab38d..f3275851 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -56,22 +56,22 @@ Which is being rendered on GitHub as: ## Detailed Design - +Before explaining the design, it's important to define some key terms: + +TODO + +### Type Interface + +```ts +TODO +``` ### Valid Syntax #### Labels are case-insensitive -
-Details - ```md > [!NOTE] > Useful information that users should know, even when skimming content. @@ -126,9 +126,6 @@ Which is being rendered on GitHub as: #### `!` prefix should not be surrounded by any spaces (U+0020) or tabs (U+0009). -
-Details - ```md > [ !NOTE] > Useful information that users should know, even when skimming content. @@ -187,6 +184,34 @@ Which is being rendered on GitHub as: > [ ! NOTE] > Useful information that users should know, even when skimming content. +#### Alert syntax should not be enclosed in HTML opening or closing tags. + +```md +
+> [!NOTE] +> Useful information that users should know, even when skimming content. +
+``` + +
+> [!NOTE] +> Useful information that users should know, even when skimming content. +
+ +--- + +```md +
+Details +> [!NOTE] +> Useful information that users should know, even when skimming content. +
+``` + +
+Details +> [!NOTE] +> Useful information that users should know, even when skimming content.
## Documentation From 2fd604777c5ed98a37f3898ccf4823e657831a41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Fri, 15 Aug 2025 22:48:57 +0900 Subject: [PATCH 07/29] wip --- .../README.md | 38 +++++++++++++++++++ 1 file changed, 38 insertions(+) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index f3275851..7df0eaba 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -201,17 +201,55 @@ TODO --- ```md +
+ +> [!NOTE] +> Useful information that users should know, even when skimming content. + +
+``` + +
+ +> [!NOTE] +> Useful information that users should know, even when skimming content. + +
+ +--- + +```md +
+Details +> [!NOTE] +> Useful information that users should know, even when skimming content. +
+``` +
Details > [!NOTE] > Useful information that users should know, even when skimming content. +
+ +--- + +```md +
+Details + +> [!NOTE] +> Useful information that users should know, even when skimming content. +
```
Details + > [!NOTE] > Useful information that users should know, even when skimming content. +
## Documentation From b1d0f0f1f9d8d6a40d39f91316a9e7d0c0a580ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Fri, 15 Aug 2025 23:00:10 +0900 Subject: [PATCH 08/29] wip --- .../README.md | 37 ++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 7df0eaba..233f8faf 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -272,6 +272,8 @@ TODO implementing this RFC as possible. --> +1. It's not an official GitHub Flavored Markdown specification. + ## Backwards Compatibility Analysis +Adding the `alert` option to the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) field will not affect existing functionality in `@eslint/markdown@7`. + +This option can be enabled by default when `@eslint/markdown@8` is released. + +```diff +// eslint.config.js +import { defineConfig } from "eslint/config"; +import markdown from "@eslint/markdown"; + +export default defineConfig([ + { + files: ["**/*.md"], + plugins: { + markdown + }, + language: "markdown/gfm", + languageOptions: { + frontmatter: "yaml", // Or pass `"toml"` or `"json"` to enable TOML or JSON front matter parsing. ++ alert: true // Enable GFM Alert syntax parsing + }, + rules: { + "markdown/no-html": "error" + } + } +]); +``` + ## Alternatives - -1. It's not an official GitHub Flavored Markdown specification. +1. This is not part of the official CommonMark or GitHub Flavored Markdown specifications. +2. It may not be widely adopted outside of GitHub, which could lead to inconsistencies in Markdown parsing across different platforms. ## Backwards Compatibility Analysis - - Adding the `alert` option to the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) field will not affect existing functionality in `@eslint/markdown@7`. -This option can be enabled by default when `@eslint/markdown@8` is released. +If desired, this option could be enabled by default in `@eslint/markdown@8`. ```diff // eslint.config.js @@ -472,63 +465,41 @@ export default defineConfig([ ## Alternatives - +### Pre-existing Implementations -## Open Questions +There are existing implementations of GFM Alert syntax parsing in other Markdown and HTML parsers: - +1. Will the `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` plugins be published as separate packages? ## Help Needed - +I'd appreciate any guidance while I work on this, or help from anyone willing to take it on. ## Frequently Asked Questions - +N/A ## Related Discussions - +### The reasons why GitHub Alert syntax is not included in Mdast -- The reasons why GitHub Alert syntax is not included in Mdast: - - https://github.com/syntax-tree/mdast-util-gfm/issues/2 - - https://github.com/orgs/syntax-tree/discussions/144 +- https://github.com/syntax-tree/mdast-util-gfm/issues/2 +- https://github.com/orgs/syntax-tree/discussions/144 -- `micromark-util` library reference: - - TODO +### `micromark-extension` references -- `mdast-util` library reference: - - `mdast-util-math`: https://github.com/syntax-tree/mdast-util-math +- Creating a micromark extension: https://github.com/micromark/micromark?tab=readme-ov-file#creating-a-micromark-extension -- `rehype-github-alert` library reference: - - https://github.com/rehypejs/rehype-github/tree/main/packages/alert#rehype-github-alert +### `mdast-util` references + +- `mdast-util-math`: https://github.com/syntax-tree/mdast-util-math +- `mdast-util-gfm-task-list-item`: https://github.com/syntax-tree/mdast-util-gfm-task-list-item \ No newline at end of file From 0107f2c19769c35e0538fe0f31b5d745d92a469d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:04:17 +0900 Subject: [PATCH 13/29] wip --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index ed86e3cc..96772af1 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -424,10 +424,7 @@ Here are some examples of invalid GFM Alert syntax: ## Documentation - +We need to update the [`README.md`](https://github.com/eslint/markdown?tab=readme-ov-file#eslint-markdown-language-plugin) for `@eslint/markdown` to include details about the new GFM Alert syntax parsing feature. In particular, we should document the new `alert` option under the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) section. ## Drawbacks From 2bc5ee0ea3c27f7ae338b802f9fbefad892e79b6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:12:30 +0900 Subject: [PATCH 14/29] wip: cleanup --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 96772af1..aed12c85 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -7,7 +7,7 @@ ## Summary -This RFC proposes adding support for GFM Alert syntax parsing to the `@eslint/markdown` package by implementing `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` custom plugin logic, and also includes the formal specification based on the [CommonMark spec](https://spec.commonmark.org/) and the [GitHub Flavored Markdown spec](https://github.github.com/gfm/). +This RFC proposes adding support for GFM Alert syntax parsing to the [`@eslint/markdown`](https://github.com/eslint/markdown) package by implementing `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` custom plugin logic, and also includes the formal specification based on the [CommonMark spec](https://spec.commonmark.org/) and the [GitHub Flavored Markdown spec](https://github.github.com/gfm/). ## Motivation @@ -15,7 +15,7 @@ The motivation for this RFC comes from [eslint/markdown#294](https://github.com/ Currently, GitHub supports a special syntax for alerts that isn't mentioned in the [GitHub Flavored Markdown spec](https://github.github.com/gfm/) and isn't parsed by the existing [`micromark-extension-gfm`](https://github.com/micromark/micromark-extension-gfm?tab=readme-ov-file#when-to-use-this) and [`mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm?tab=readme-ov-file#when-to-use-this) packages, which are used internally by `@eslint/markdown` to parse Markdown content and create AST nodes. -Inconsistencies between GitHub's GFM alert syntax and existing Markdown parsers cause false positives and false negatives in some situations, especially when writing rules whose syntax overlaps with GitHub's alert syntax. +Inconsistencies between GitHub's GFM alert syntax and existing Markdown parsers can cause false positives and false negatives in some cases, especially when writing rules that detect error-prone syntax and when the syntax overlaps with GitHub's alert syntax. This RFC aims to address that gap by introducing the necessary parsing logic and formal specification for GFM Alert syntax. From 60273422354ad30f9c9e7ca5c7a2817e6d214ba0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:19:33 +0900 Subject: [PATCH 15/29] wip: add invalid syntaxes --- .../README.md | 30 +++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index aed12c85..fffe0394 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -354,6 +354,36 @@ Here are some examples of invalid GFM Alert syntax: > [!NOTE] hi > Useful information that users should know, even when skimming content. +#### Single-line GFM Alert syntax (without content) isn't working + +```md +> [!NOTE] +``` + +> [!NOTE] + +--- + +```md +> [!NOTE] +> +``` + +> [!NOTE] +> + +#### Nested GFM Alert syntax isn't working + +```md +> > [!NOTE] +> > Useful information that users should know, even when skimming content. +``` + +--- + +> > [!NOTE] +> > Useful information that users should know, even when skimming content. + #### GFM Alert syntax should not be enclosed in HTML opening or closing tags ```md From eaa84ab0ed4027c4d6887919418a9ec4ff1e707b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:27:07 +0900 Subject: [PATCH 16/29] wip: add more valid syntax --- .../README.md | 40 +++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index fffe0394..2805c04e 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -250,6 +250,46 @@ Here are some examples of valid GFM Alert syntax: > [!NOTE] > Useful information that users should know, even when skimming content. +#### Upto 3 indented ***space*** is allowed before the ***closing angle bracket*** + +```md +> [!NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [!NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md + > [!NOTE] + > Useful information that users should know, even when skimming content. +``` + + > [!NOTE] + > Useful information that users should know, even when skimming content. + +--- + +```md + > [!NOTE] + > Useful information that users should know, even when skimming content. +``` + + > [!NOTE] + > Useful information that users should know, even when skimming content. + +--- + +```md + > [!NOTE] + > Useful information that users should know, even when skimming content. +``` + + > [!NOTE] + > Useful information that users should know, even when skimming content. + ### Invalid Syntax Here are some examples of invalid GFM Alert syntax: From 5e2d0dd30ce43514ef812a68bb41b65d659bd7a5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:32:09 +0900 Subject: [PATCH 17/29] wip: add invalid syntax --- .../README.md | 20 +++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 2805c04e..d0eea18f 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -374,6 +374,26 @@ Here are some examples of invalid GFM Alert syntax: > [!NOTE ] > Useful information that users should know, even when skimming content. +#### Only ***space***s and ***tab***s are allowed before the ***opening square bracket*** + +```md +> hi[!NOTE] +> Useful information that users should know, even when skimming content. +``` + +> hi[!NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md +> hi [!NOTE] +> Useful information that users should know, even when skimming content. +``` + +> hi [!NOTE] +> Useful information that users should know, even when skimming content. + #### Only ***space***s, ***tab***s, and ***line ending***s are allowed after the ***closing square bracket*** ```md From 4f0d8523e7a7743f5f13fd334bd56c3f57989cdf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:35:25 +0900 Subject: [PATCH 18/29] wip: add invalid cases --- .../2025-support-gfm-alert-syntax-parsing/README.md | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index d0eea18f..97f6d7e8 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -439,11 +439,19 @@ Here are some examples of invalid GFM Alert syntax: > > Useful information that users should know, even when skimming content. ``` ---- - > > [!NOTE] > > Useful information that users should know, even when skimming content. +--- + +```md +- > [!NOTE] +- > Useful information that users should know, even when skimming content. +``` + +- > [!NOTE] +- > Useful information that users should know, even when skimming content. + #### GFM Alert syntax should not be enclosed in HTML opening or closing tags ```md From 959c8e7e22f34478a79985d8507cfc8923f28165 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:40:45 +0900 Subject: [PATCH 19/29] wip: add invalid syntax --- .../README.md | 26 ++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 97f6d7e8..2836303c 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -414,7 +414,7 @@ Here are some examples of invalid GFM Alert syntax: > [!NOTE] hi > Useful information that users should know, even when skimming content. -#### Single-line GFM Alert syntax (without content) isn't working +#### GFM Alert syntax without content isn't working ```md > [!NOTE] @@ -432,6 +432,30 @@ Here are some examples of invalid GFM Alert syntax: > [!NOTE] > +#### Multi-line GFM Alert syntax isn't working + +```md +> [ +> !NOTE] +> Useful information that users should know, even when skimming content. +``` + +> [ +> !NOTE] +> Useful information that users should know, even when skimming content. + +--- + +```md +> [!NOTE +> ] +> Useful information that users should know, even when skimming content. +``` + +> [!NOTE +> ] +> Useful information that users should know, even when skimming content. + #### Nested GFM Alert syntax isn't working ```md From b919b7e40be4c98edacc3e303d2df6e022ca138d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:43:45 +0900 Subject: [PATCH 20/29] wip: casing --- .../README.md | 30 +++++++++---------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 2836303c..a722c8a5 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -3,11 +3,11 @@ - RFC PR: https://github.com/eslint/rfcs/pull/138 - Authors: 루밀LuMir(lumirlumir) -# Support GFM Alert syntax parsing +# Support GFM alert syntax parsing ## Summary -This RFC proposes adding support for GFM Alert syntax parsing to the [`@eslint/markdown`](https://github.com/eslint/markdown) package by implementing `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` custom plugin logic, and also includes the formal specification based on the [CommonMark spec](https://spec.commonmark.org/) and the [GitHub Flavored Markdown spec](https://github.github.com/gfm/). +This RFC proposes adding support for GFM alert syntax parsing to the [`@eslint/markdown`](https://github.com/eslint/markdown) package by implementing `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` custom plugin logic, and also includes the formal specification based on the [CommonMark spec](https://spec.commonmark.org/) and the [GitHub Flavored Markdown spec](https://github.github.com/gfm/). ## Motivation @@ -17,9 +17,9 @@ Currently, GitHub supports a special syntax for alerts that isn't mentioned in t Inconsistencies between GitHub's GFM alert syntax and existing Markdown parsers can cause false positives and false negatives in some cases, especially when writing rules that detect error-prone syntax and when the syntax overlaps with GitHub's alert syntax. -This RFC aims to address that gap by introducing the necessary parsing logic and formal specification for GFM Alert syntax. +This RFC aims to address that gap by introducing the necessary parsing logic and formal specification for GFM alert syntax. -GFM Alert syntax is a way to create attention-grabbing blocks in Markdown content. It uses a specific syntax to denote different types of alerts, such as notes, tips, warnings, and more. The basic structure of a GFM Alert is as follows: +GFM alert syntax is a way to create attention-grabbing blocks in Markdown content. It uses a specific syntax to denote different types of alerts, such as notes, tips, warnings, and more. The basic structure of a GFM alert is as follows: ```md > [!NOTE] @@ -73,7 +73,7 @@ Before explaining the design, it's important to define some key terms: ### Type Interface -Since GFM Alert syntax is part of blockquote syntax from Markdown, `Alert` interface extends [`Blockquote`](https://github.com/syntax-tree/mdast?tab=readme-ov-file#blockquote) node type of Mdast. +Since GFM alert syntax is part of blockquote syntax from Markdown, `Alert` interface extends [`Blockquote`](https://github.com/syntax-tree/mdast?tab=readme-ov-file#blockquote) node type of Mdast. ```ts import type { Blockquote } from "mdast"; @@ -98,7 +98,7 @@ interface Alert extends Blockquote { ### Valid Syntax -Here are some examples of valid GFM Alert syntax: +Here are some examples of valid GFM alert syntax: #### `NOTE`, `TIP`, `IMPORTANT`, `WARNING` and `CAUTION` are valid ***label***s @@ -292,7 +292,7 @@ Here are some examples of valid GFM Alert syntax: ### Invalid Syntax -Here are some examples of invalid GFM Alert syntax: +Here are some examples of invalid GFM alert syntax: #### ***exclamation mark*** should not be surrounded by any ***space***s or ***tab***s @@ -414,7 +414,7 @@ Here are some examples of invalid GFM Alert syntax: > [!NOTE] hi > Useful information that users should know, even when skimming content. -#### GFM Alert syntax without content isn't working +#### GFM alert syntax without content isn't working ```md > [!NOTE] @@ -432,7 +432,7 @@ Here are some examples of invalid GFM Alert syntax: > [!NOTE] > -#### Multi-line GFM Alert syntax isn't working +#### Multi-line GFM alert syntax isn't working ```md > [ @@ -456,7 +456,7 @@ Here are some examples of invalid GFM Alert syntax: > ] > Useful information that users should know, even when skimming content. -#### Nested GFM Alert syntax isn't working +#### Nested GFM alert syntax isn't working ```md > > [!NOTE] @@ -476,7 +476,7 @@ Here are some examples of invalid GFM Alert syntax: - > [!NOTE] - > Useful information that users should know, even when skimming content. -#### GFM Alert syntax should not be enclosed in HTML opening or closing tags +#### GFM alert syntax should not be enclosed in HTML opening or closing tags ```md
@@ -546,7 +546,7 @@ Here are some examples of invalid GFM Alert syntax: ## Documentation -We need to update the [`README.md`](https://github.com/eslint/markdown?tab=readme-ov-file#eslint-markdown-language-plugin) for `@eslint/markdown` to include details about the new GFM Alert syntax parsing feature. In particular, we should document the new `alert` option under the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) section. +We need to update the [`README.md`](https://github.com/eslint/markdown?tab=readme-ov-file#eslint-markdown-language-plugin) for `@eslint/markdown` to include details about the new GFM alert syntax parsing feature. In particular, we should document the new `alert` option under the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) section. ## Drawbacks @@ -573,7 +573,7 @@ export default defineConfig([ language: "markdown/gfm", languageOptions: { frontmatter: "yaml", // Or pass `"toml"` or `"json"` to enable TOML or JSON front matter parsing. -+ alert: true // Enable GFM Alert syntax parsing ++ alert: true // Enable GFM alert syntax parsing }, rules: { "markdown/no-html": "error" @@ -588,7 +588,7 @@ I cannot find any significant alternatives to this proposal. but I am open to su ### Pre-existing Implementations -There are existing implementations of GFM Alert syntax parsing in other Markdown and HTML parsers: +There are existing implementations of GFM alert syntax parsing in other Markdown and HTML parsers: - `rehype-github-alert`: https://github.com/rehypejs/rehype-github/tree/main/packages/alert#rehype-github-alert - `markdown-it-github-alert`: https://github.com/antfu/markdown-it-github-alerts @@ -609,7 +609,7 @@ N/A ## Related Discussions -### The reasons why GitHub Alert syntax is not included in Mdast +### The reasons why GitHub alert syntax is not included in Mdast - https://github.com/syntax-tree/mdast-util-gfm/issues/2 - https://github.com/orgs/syntax-tree/discussions/144 From 562d22032974111ebd759136bd4e8e44e06de77b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:46:55 +0900 Subject: [PATCH 21/29] wip --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index a722c8a5..3352de9c 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -555,7 +555,7 @@ We need to update the [`README.md`](https://github.com/eslint/markdown?tab=readm ## Backwards Compatibility Analysis -Adding the `alert` option to the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) field will not affect existing functionality in `@eslint/markdown@7`. +Adding the `alert` option to the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) and set it to `false` by default will not affect existing functionality in `@eslint/markdown@7`. If desired, this option could be enabled by default in `@eslint/markdown@8`. From f9f6cf1dabc99e19b5b2a2c77072161310d77186 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 19 Aug 2025 22:49:05 +0900 Subject: [PATCH 22/29] wip --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 3352de9c..5d9e3141 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -573,7 +573,7 @@ export default defineConfig([ language: "markdown/gfm", languageOptions: { frontmatter: "yaml", // Or pass `"toml"` or `"json"` to enable TOML or JSON front matter parsing. -+ alert: true // Enable GFM alert syntax parsing ++ alert: true // Enable GFM alert syntax parsing (default: `false`) }, rules: { "markdown/no-html": "error" From 181503d4a77ef9525862550aee780b72b20b7380 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Mon, 1 Sep 2025 23:53:17 +0900 Subject: [PATCH 23/29] wip: add explanatory --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 5d9e3141..22f22b22 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -100,7 +100,7 @@ interface Alert extends Blockquote { Here are some examples of valid GFM alert syntax: -#### `NOTE`, `TIP`, `IMPORTANT`, `WARNING` and `CAUTION` are valid ***label***s +#### All of the following are valid ***label***s: `NOTE`, `TIP`, `IMPORTANT`, `WARNING` and `CAUTION` ```md > [!NOTE] From f4cbe11832e86db650153c6c074792ab2595329c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 2 Sep 2025 00:01:01 +0900 Subject: [PATCH 24/29] wip: why wouldn't we use pre-existing implementations --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 22f22b22..cc1d1d04 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -593,6 +593,8 @@ There are existing implementations of GFM alert syntax parsing in other Markdown - `rehype-github-alert`: https://github.com/rehypejs/rehype-github/tree/main/packages/alert#rehype-github-alert - `markdown-it-github-alert`: https://github.com/antfu/markdown-it-github-alerts +However, these plugins cannot be used in the `eslint/markdown` package, because `rehype-github-alert` is a plugin for `rehype` (which uses [HAST](https://github.com/syntax-tree/hast#readme) AST) and `markdown-it-github-alert` is a plugin for `markdown-it` (which uses its own Markdown AST), while `eslint/markdown` parses Markdown using `micromark` and `mdast` (which uses [MDAST](https://github.com/syntax-tree/mdast#readme) AST). + ## Open Questions 1. Will the `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` plugins be published as separate packages? From 99a58b53758da50e80a293d5870bc3371d8a2093 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 2 Sep 2025 22:27:50 +0900 Subject: [PATCH 25/29] wip: add answers for questions --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index cc1d1d04..ef3f2500 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -597,7 +597,8 @@ However, these plugins cannot be used in the `eslint/markdown` package, because ## Open Questions -1. Will the `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` plugins be published as separate packages? +- Question 1. Will the `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` plugins be published as separate packages? +- Answer 1. According to the [comment](https://github.com/eslint/rfcs/pull/138#discussion_r2288501879), it is not preferred to have additional packages to maintain for this. ## Help Needed From 039055add9102c1d9f054d91f33238599b64ca7b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 2 Sep 2025 22:40:51 +0900 Subject: [PATCH 26/29] wip: add more explanatory text --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index ef3f2500..9ac3966a 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -11,7 +11,7 @@ This RFC proposes adding support for GFM alert syntax parsing to the [`@eslint/m ## Motivation -The motivation for this RFC comes from [eslint/markdown#294](https://github.com/eslint/markdown/issues/294) and [eslint/markdown#449](https://github.com/eslint/markdown/issues/449). +The motivation for this RFC comes from [eslint/markdown#294](https://github.com/eslint/markdown/issues/294). Currently, GitHub supports a special syntax for alerts that isn't mentioned in the [GitHub Flavored Markdown spec](https://github.github.com/gfm/) and isn't parsed by the existing [`micromark-extension-gfm`](https://github.com/micromark/micromark-extension-gfm?tab=readme-ov-file#when-to-use-this) and [`mdast-util-gfm`](https://github.com/syntax-tree/mdast-util-gfm?tab=readme-ov-file#when-to-use-this) packages, which are used internally by `@eslint/markdown` to parse Markdown content and create AST nodes. @@ -150,7 +150,9 @@ Here are some examples of valid GFM alert syntax: > [!CAUTION] > Advises about risks or negative outcomes of certain actions. -#### ***Label***s are case-insensitive +#### All of the following are case-insensitive ***label***s: `NOTE`, `TIP`, `IMPORTANT`, `WARNING` and `CAUTION` + +The example below shows only `NOTE`, but it applies to all labels such as `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`. ```md > [!NOTE] From 639b0dd565a0ff3f9a9a002ed3f17701473fb3e7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 2 Sep 2025 22:44:16 +0900 Subject: [PATCH 27/29] wip: add more explanatory text --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 9ac3966a..28c4dc97 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -204,6 +204,8 @@ The example below shows only `NOTE`, but it applies to all labels such as `TIP`, #### Upto 4 indented ***space*** is allowed before the ***opening square bracket*** +The example below shows only `NOTE`, but it applies to all labels such as `TIP`, `IMPORTANT`, `WARNING`, and `CAUTION`. + ```md >[!NOTE] > Useful information that users should know, even when skimming content. From 6519cd52eb0378b3601b4635aa967e5353b15551 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 2 Sep 2025 23:16:43 +0900 Subject: [PATCH 28/29] wip: add more details --- .../README.md | 74 ++++++++++++------- 1 file changed, 49 insertions(+), 25 deletions(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index 28c4dc97..a7111711 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -71,6 +71,53 @@ Before explaining the design, it's important to define some key terms: - ***line ending***: According to the [CommonMark spec](https://spec.commonmark.org/0.31.2/#line-ending), A line ending is a line feed (U+000A), a carriage return (U+000D) not followed by a line feed, or a carriage return and a following line feed. - ***label***: The text that appears inside the ***opening square bracket*** and ***closing square bracket*** and is prefixed by an ***exclamation mark***. It determines the style and semantics of the alert. +### GFM alert syntax in plugins and configs + +This suggestion requires adding an option to `languageOptions` in the `@eslint/markdown` to enable parsing of GFM alert syntax. + +`micromark-extension-gfm-alert` and `mdast-util-gfm-alert` complement each other and are intended to be used together to provide full support for the GFM alert syntax. + +To enable parsing of GFM alert syntax, set the `alert` option to `true`; set it to `false` to disable it. Only the boolean values `true` and `false` are accepted. + +Adding the `alert` option to the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) and set it to `false` by default will not affect existing functionality in `@eslint/markdown@7` (version 7.x.x). + +If desired, this option could be enabled by default in `@eslint/markdown@8` (version 8.x.x). + +```diff +// eslint.config.js +import { defineConfig } from "eslint/config"; +import markdown from "@eslint/markdown"; + +export default defineConfig([ + { + files: ["**/*.md"], + plugins: { + markdown + }, + language: "markdown/gfm", + languageOptions: { + frontmatter: "yaml", // Or pass `"toml"` or `"json"` to enable TOML or JSON front matter parsing. ++ alert: true // Enable GFM alert syntax parsing (default: `false`) + }, + rules: { + "markdown/no-html": "error" + } + } +]); +``` + +### Where would the `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` packages live? + +#### `micromark-extension-gfm-alert` + +- `micromark-extension-gfm-alert` source code logic would be implemented in the `src/extensions/micromark-extension-gfm-alert.js` file. +- `micromark-extension-gfm-alert` test files would be implemented in the `tests/extensions/micromark-extension-gfm-alert.test.js` file. + +#### `mdast-util-gfm-alert` + +- `mdast-util-gfm-alert` source code logic would be implemented in the `src/extensions/mdast-util-gfm-alert.js` file. +- `mdast-util-gfm-alert` test files would be implemented in the `tests/extensions/mdast-util-gfm-alert.test.js` file. + ### Type Interface Since GFM alert syntax is part of blockquote syntax from Markdown, `Alert` interface extends [`Blockquote`](https://github.com/syntax-tree/mdast?tab=readme-ov-file#blockquote) node type of Mdast. @@ -559,32 +606,9 @@ We need to update the [`README.md`](https://github.com/eslint/markdown?tab=readm ## Backwards Compatibility Analysis -Adding the `alert` option to the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) and set it to `false` by default will not affect existing functionality in `@eslint/markdown@7`. - -If desired, this option could be enabled by default in `@eslint/markdown@8`. - -```diff -// eslint.config.js -import { defineConfig } from "eslint/config"; -import markdown from "@eslint/markdown"; +This proposal is fully backward-compatible, as it only adds new options and does not remove or modify existing features. -export default defineConfig([ - { - files: ["**/*.md"], - plugins: { - markdown - }, - language: "markdown/gfm", - languageOptions: { - frontmatter: "yaml", // Or pass `"toml"` or `"json"` to enable TOML or JSON front matter parsing. -+ alert: true // Enable GFM alert syntax parsing (default: `false`) - }, - rules: { - "markdown/no-html": "error" - } - } -]); -``` +No changes are required from end users. ## Alternatives From a5e9273fa02747a0f152b6fca06681f093ff9be8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EB=A3=A8=EB=B0=80LuMir?= Date: Tue, 2 Sep 2025 23:23:30 +0900 Subject: [PATCH 29/29] wip --- designs/2025-support-gfm-alert-syntax-parsing/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/designs/2025-support-gfm-alert-syntax-parsing/README.md b/designs/2025-support-gfm-alert-syntax-parsing/README.md index a7111711..7db6bf2e 100644 --- a/designs/2025-support-gfm-alert-syntax-parsing/README.md +++ b/designs/2025-support-gfm-alert-syntax-parsing/README.md @@ -77,7 +77,7 @@ This suggestion requires adding an option to `languageOptions` in the `@eslint/m `micromark-extension-gfm-alert` and `mdast-util-gfm-alert` complement each other and are intended to be used together to provide full support for the GFM alert syntax. -To enable parsing of GFM alert syntax, set the `alert` option to `true`; set it to `false` to disable it. Only the boolean values `true` and `false` are accepted. +To enable parsing of GFM alert syntax, set the `languageOptions.alert` option to `true`; set it to `false` to disable it. Only the boolean values `true` and `false` are accepted. Adding the `alert` option to the [Language Options](https://github.com/eslint/markdown?tab=readme-ov-file#language-options) and set it to `false` by default will not affect existing functionality in `@eslint/markdown@7` (version 7.x.x).