feat(markdown): add support for GFM noteblocks proposal

[queengooborg]

Summary

This PR adds support for the GFM noteblocks proposal by performing the following changes:

• Adds parsing support for the GFM noteblocks proposed syntax (see link above), performing transformations to add the magic text, leaving no noticeable differences
  • The callout type has also been added, even though the GFM proposal does not include such a type
  • The text for the three new noteblock types was localized using machine translation for all other locales
• Adds code for the tip, important and caution types when we're ready to add them
  • Currently disabled, per feat(markdown): add support for GFM noteblocks proposal #10168 (comment)
  • New icons for these types have been created by splicing together elements from existing icons
  • The light bulb for the new tip icon was created in-house by a vector artist from my company, Gooborg Studios

---

Screenshots

Before

After

---

How did you test this change?

Markdown used:

## MDN Style

> **Note:** Note!

> **Tip:** A helpful tip

> **Important:** Something important

> **Warning:** Be weary of this!

> **Caution:** Don't set this thing!

> **Callout:** Some call to action!

---

## GFM Proposal Style

> [!NOTE]
> Note!

> [!TIP]
> A helpful tip

> [!IMPORTANT]
> Something important

> [!WARNING]
> Be weary of this!

> [!CAUTION]
> Don't set this thing!

> [!CALLOUT]
> Some call to action!

[wbamberg]

I'm in favour of using the new GFM syntax, but I don't know why people want so many different kinds of admonitions. Warning, caution, note, tip, important... people will have no idea when to use which. I think it would be better to adopt this syntax for the admonitions we currently support and disallow the rest. More is not always better.

[teoli2003]

More is not always better.

Yes, and if more is needed, we can always open a PR and have a discussion about the pertinence of it.

I also like using more standard syntax.

[queengooborg]

I've just pushed a commit to stick with the three existing noteblock types, but I've kept the styling, new icons, etc. in place so that we can easily add them in if/when we want to!

[fiji-flo]

He we're (@caugner @argl) are fine with migrating to the new syntax. However, if we only support *Note", "Warning" and "Callout" let's remove support for the others. And I'd need some comment from the content team (@Rumyra). Would it then be okay to bulk change mdn/content and mdn/translated-content?

[yin1999]

/cc @mdn/yari-content-zh

I'm +1 for this, as this would solve the problem where we currently have to add spaces between the prefix and the content to make sure that the markdown parser can correctly handle the bold syntax:

The follow markdown content could not be parsed as we expected:

> **备注：**你好世界

Result:

<p>**备注：**你好世界</p>

[wbamberg]

We'd also need a corresponding update to https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN.

[queengooborg]

let's remove support for the others.

The other three are disabled, so only the three we actively use are supported. There is simply code and assets available for when and if we want to enable them!

Would it then be okay to bulk change mdn/content and mdn/translated-content?

Yes, we could most definitely do a bulk update! Since this PR doesn't remove support for the "MDN syntax", we can perform the update gradually too. We can then follow up and drop support for the old notes syntax if we want to!

[caugner]

We (@argl @fiji-flo @caugner) took a look today and decided to approve the changes to support the GFM noteblocks proposal syntax for the three existing notecard types (note, warning, callout), but to reject the other changes preparing for hypothetically adding support for the other types.

Can you please revert the changes regarding the other noteblock types? We will then give it another review and merge the PR asap.

[queengooborg]

The code from other noteblocks has now been removed -- I'll create another PR that includes that spliced-out code/data as a sort of proposal, so if we do want to add them in, we can merge that PR without needing to redo any existing work!

(By the way, no need to set my PRs as drafts when requesting reviews -- I get to them pretty quickly. :P)

[caugner]

Can you explain this change?

[queengooborg]

This allows for a much easier lookup using GFM notecard keywords. The logic is reversed when using MDN-flavored syntax, so it iterates through each entry to find the applicable type.

[caugner]

Would it make sense to add (key, value) and (value, key) to the map to allow both directions, or is there a risk for a collision? In either case, let's add a comment above to give an example what msgid and msgstr[0] refer to to help.

Also, let's update the JSDoc of the method to clearly indicate what the returning map contains.

[queengooborg]

It might make sense to have variables for both formats, but I feel that if we are planning to migrate to GFM syntax, then I think it makes more sense to just have the one format, as it will make removal of the old syntax parsing much quicker.

[caugner]

I feel like we shouldn't support callout here, if it isn't part of the GFM noteblocks proposal (and therefore not rendered by GitHub):

[!CALLOUT]
Callout

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

@mdn/core-yari-content What do you think?

[queengooborg]

Note: if we remove support for callouts in the GFM syntax, we'd have to special-case it for the original syntax. If the decision is not to support callouts in GFM syntax, then we should overhaul all existing callouts too.