Add support for notes in GitHub syntax

[jelovirt]

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

Note

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

Important

Crucial information necessary for users to succeed.

Warning

Critical content demanding immediate user attention due to potential risks.

Related links

• https://github.com/orgs/community/discussions/16925
• https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts

[infotexture]

👍 Probably makes sense to support GitHub's syntax, but they support different variants in different places — and no one syntax works everywhere — even on their own platform.

2022 beta: blockquote syntax with bold labels

On May 10, 2022, a blockquote-based syntax was initially proposed in
community/community#16925:

To better highlight and separate certain information from the rest in your documentation on GitHub, we now render a special and accessible note or warning blockquote in Markdown documents. We are using the existing syntax for blockquote and bold text.

> **Note**
> This is a note

> **Warning**
> This is a warning

This syntax is still supported, and rendered in README files with icons and special admonition styling like the newer 2023 format shown in the issue description above:

Note
This is a note

🎗️ This initial syntax has the advantage that it degrades gracefully to standard blockquote rendering in wikis, where the bold label is preserved (just without the icon & color).

In addition to the multiline format, this syntax can be compressed to a single line as follows:

> **Note:** This is a note.

Note: This is a note.

This format is now deprecated per https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts:

Note: The syntax used during the beta testing period is now deprecated and will be removed.

2023 Alert syntax

As of July 21, 2023, the bold labels from the initial proposal were replaced with a new [!NOTE] label syntax, and an IMPORTANT alert type was added to the note and warning types in the initial proposal:

> [!NOTE]  
> Highlights information that users should take into account, even when skimming.

> [!IMPORTANT]  
> Crucial information necessary for users to succeed.

> [!WARNING]  
> Critical content demanding immediate user attention due to potential risks.

Warning

This new syntax does not degrade as gracefully in wikis, where the labels appear verbatim as [!NOTE].

Docusaurus

In addition to the GitHub format(s), we might want to consider the remark-admonitions syntax used by Docusaurus (and several other tools), which supports several DITA-compatible types.

https://docusaurus.io/docs/markdown-features/admonitions

In addition to the basic Markdown syntax, we have a special admonitions syntax by wrapping text with a set of 3 colons, followed by a label denoting its type.

:::note

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::tip

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::info

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::caution

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

:::danger

Some **content** with _Markdown_ `syntax`. Check [this `api`](#).

:::

In this syntax, custom titles can be specified after the type label:

:::note Your Title

[infotexture]

If support were added for additional admonition formats in Markdown input, we'd need to consider how to configure which format should be generated for DITA <note> elements in Markdown output. 🤔