Markdown Admonitions

Enables Docusaurus-style and MkDocs-style admonitions in the VS Code preview.

Features

Several static site generators for documentation including Docusaurus have support for informational hints in the documentation. This extension allows for the preview to show Docusaurus and MkDocs admonitions. MkDocs style admonitions fall back to a default and docusaurus style only renders known types.

Examples:

:::note
Remember, the best time to plant a tree was 20 years ago.
The second best time is now. So, plant that code!
:::

!!! note
    *here be dragons*

??? note
    This is hidden unless expanded.

This and the other divs will be displayed like this in dark mode in VS Code:

They can also be stacked:

The markdown for the four divs will be shown like above if the extension is enabled. Otherwise they will be four paragraphs of text.

Additional info at Docusaurus.

Based on markdown-it, markdown-it-container and markdown-it-admon.

Requirements

Runs in Visual Studio Code.

Extension Settings

This extension contributes the following settings:

• markdownAdmonitions.enable: Enable/disable this extension.
• markdownAdmonitions.mode: Choose which admonition syntax to render:
  • relaxed (default): Docusaurus and Nextcloud fenced admonitions, plus MkDocs admonitions.
  • strict-docusaurus: Current Docusaurus syntax with canonical keywords, optional Markdown titles, IDs, and classes.
  • strict-nextcloud: Nextcloud keywords (info, warn, success, error, question), mapped to Docusaurus styles.
  • strict-mkdocs: MkDocs-style admonitions.

Nextcloud keywords can also be used in relaxed mode. For example, ::: warn is rendered as a warning admonition.

In strict-docusaurus mode, titles are displayed in uppercase to match Docusaurus. In relaxed mode, generated titles remain lowercase and custom titles keep their authored casing. Custom Docusaurus titles go in optional square brackets, and IDs/classes go in optional braces:

:::note[Remember **this**]{#important .custom-class}
Admonition content.
:::

The square brackets are only required when specifying a title. The braces and their ID/class attributes are optional.

Known Issues

None.