infotexture
commented
1 year ago 👍 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 https://github.com/community/community/discussions/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 warningThis 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
Related links