Block Editor Handbook: Convert GitHub alert markup into callout markup in the handbook

[ndiego]

GitHub has introduced markup that allows you to easily create alerts. They look like this:

Note

An example note.

In the Handbook, we have callouts, and these need to be created using straight HTML in the documentation .md files. They look like this:

<div class="callout callout-tip">
    An example tip.
</div>

The problem is that these callouts do not look like callouts/alerts when viewed on GitHub. Here's an example of how they look in the Handbook and how they look in GitHub.

Similarly, if you use the GitHub alert markup, they will appear as block quotes in the Handbook. This is an example of the warning syntax look in GitHub and how they look in the Handbook.

The perfect solution would be for contributors to use the alert markup in the .md files, and then have a way to automatically convert this markup into the current callout HTML in the Handbook. GitHub only supports three types of alerts, and we currently have four callouts. If implemented, I recommend the Tip callout not be mapped to the GitHub alert. It's essentially the same as an Info callout.

[jonathanbossenger]

Adding an update here, it looks like GitHub now supports 5 callout types

Note

Highlights information that users should take into account, even when skimming.

Tip

Optional information to help a user be more successful.

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Caution

Negative potential consequences of an action.

These could be mapped to the 5 callout variations that exist for .org

Adding this support would also tremendously help the Learn.WordPress.org efforts, as we use callouts quite extensively in our written content.

[ndiego]

Thanks for the update @jonathanbossenger! Looks like we would now have a clear 1-to-1 mapping.

[adamwoodnz]

Transferring this to mu-plugins as we'll need to handle the conversion there, likely into a notice block.

[adamwoodnz]

Once complete we can remove the temporary styles added to the Developer theme.