Today, I learned that GitHub recently added support for admonitions in Markdown. Github calls them Alerts and – since it's a Github flavored Markdown extension – they only render on GitHub: GitHub docs
Alerts come in 5 kinds, NOTE, TIP, IMPORTANT, WARNING, CAUTION and are used by adding a [!<KIND>] tag in a blockquote:
> [!NOTE]
> alert text goes here
You can see it in action on the neo4rs repo: https://github.com/neo4j-labs/neo4rs?tab=readme-ov-file#implementation-progress
I tried to preview the rendered Markdown file with the Markdown preview extension for the gh cli and Grip – GitHub README Instant Preview. Both tools, to my knowledge, use the GitHub API to render the Markdown, but neither rendered the Alert properly at first.
The GitHub API for rendering Markdown does render the alerts properly, but only when the mode is set to gfm (the default is the markdown value):
# Use cURL to use the GitHub API, setting the `gfm` mode $ curl -L -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/markdown -d '{"text": "> [!IMPORTANT]\ntest", "mode":"gfm"}' <div class="markdown-alert markdown-alert-important"><p class="markdown-alert-title"><svg class="octicon octicon-report mr-2" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>Important</p><p>test</p> </div>
# Use cURL to use the GitHub API, setting the `markdown` mode $ curl -L -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/markdown -d '{"text": "> [!IMPORTANT]\ntest", "mode":"markdown"}' <blockquote> <p>[!IMPORTANT] test</p> </blockquote>
# Use cURL to use the GitHub API, using the default mode $ curl -L -H "Accept: application/vnd.github+json" -H "X-GitHub-Api-Version: 2022-11-28" https://api.github.com/markdown -d '{"text": "> [!IMPORTANT]\ntest"}' <blockquote> <p>[!IMPORTANT] test</p> </blockquote>
To set the correct mode for grip, you need to pass the --user-content flag, which will set the gfm internally.
gh markdown-preview does not set the gfm mode in any way, I opened an issue to see if we can add this.