yari
yari copied to clipboard
mdn
feat: Add support for GFM noteblocks proposal
Summary
This PR adds support for the GFM noteblocks proposal by performing two major 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 support for the tip, important and caution types when we're ready to add them
- Currently disabled, per https://github.com/mdn/yari/pull/10168#issuecomment-1852840252
- 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!
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.
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.
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!
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?
We'd also need a corresponding update to https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Howto/Markdown_in_MDN.
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!
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)