Add support for Alerts

[tukusejssirs]

Initial checklist

• [X] I read the support docs
• [X] I read the contributing guide
• [X] I agree to follow the code of conduct
• [X] I searched issues and couldn’t find anything (or linked relevant results below)

Problem

The Alerts feature is not properly parsed ATM.

The issue is that > [!NOTE] is converted to > \[!NOTE] ([ is escaped) which is an invalid Alert syntax.

Here are all possible alert types currently supported by GFM:

> [!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.

Solution

> [!NOTE] (and other alert types) should be left intact.

Alternatives

Of course, can remove the backslashes using String(file).replace(/^> \\\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\][ \t]*$/gm, '> [!$1]'), however, I think remark-gfm should support this out of box. :wink:

[remcohaszing]

GitHub looks at the textual meaning of the blockquote content. It works fine with escaped [ characters.

---

> \[!NOTE]
> Useful information that users should know, even when skimming content.

yields:

[!NOTE] Useful information that users should know, even when skimming content.

---

> [!NOTE]
> Useful information that users should know, even when skimming content.

[!note]: https://example.com

yields:

!NOTE Useful information that users should know, even when skimming content.

[tukusejssirs]

Thanks for taking the time to reply to my issue! :pray:

Update: It actually does work using the backslash, although it seems to me like it is not the format they recommend to be used.

[wooorm]

> [!NOTE]
Some note

[!note]: https://example.com

Yields:

!NOTE Some note

[wooorm]

I am not sure our projects here should change —— GH made a new format that interferes with references/definitions. We consider those references/definitions too. That’s why they get escaped

[tukusejssirs]

I am not sure our projects here should change.

@wooorm, well if the package name includes gfm, thus you try to support GitHub Flavored Markdown, I think it is fair to expect your goal is to support all GFM features.

That said, I see that here the GFM spec is only v0.29-gfm from 6 Apr 2019 and it does not include the alerts feature, so you might say you don’t want to add anything outside of the (latest) published spec of GFM which is fine.

GH made a new format that interferes with references/definitions.

Does it interfere? This new feature has a strict format (/^> {0,4}\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\](\n> *.*)+$/gm) which could be made an exception to the references/definitions format. Anyway, is [!NOTE] a valid reference/definition format? It could be if one defines such reference, however can it start with an exclamation mark? :thinking: Even if it can, the alerts are so strict about the formatting the alert types, it should be a big issue IMHO. That said, you know the plugin’s codebase better. :wink:

[wooorm]

As you found out, notes aren’t GFM. GFM is several syntax extensions to markdown that work everywhere on GitHub. This isn’t a syntax extension. This is AST transforms on the HTML. GH does many things to your content that aren’t GFM.

Does it interfere? Anyway, is [!NOTE] a valid reference/definition format

Yep, I just showed that: https://github.com/remarkjs/remark-gfm/issues/67#issuecomment-2198492600

The alerts are so strict about the formatting the alert types

They’re loose enough to allow that escaped [. It works, this project makes markdown that works?

[wooorm]

You might enjoy this example:

<blockquote>
<p>[!NOTE]
asd</p>
</blockquote>

[!NOTE] asd

[tukusejssirs]

Okay, @wooorm, thanks for your time. :pray:

Indeed it works as expected even with \[!NOTE]. Now I think it might be even better to keep it as is, as it lets references work in all cases.

You might enjoy this example:

When I write Markdown, I prefer not inserting HTML code unless there is a big requirement to do so. However, thanks for sharing this! :pray:

---

Feel free to close this issue. :wink: