mkdocs-callouts

A simple plugin that converts Obsidian style callouts and converts them into mkdocs supported 'admonitions' (a.k.a. callouts).

Note

For GitHub's callout syntax, this markdown extension might be what you want instead: https://github.com/dahlia/markdown-gfm-admonition

Setup

Install the plugin using pip:

pip install mkdocs-callouts

Activate the plugin in mkdocs.yml, note that some markdown_extensions are required for this plugin to function correctly:

markdown_extensions:
  - nl2br
  - admonition
  - pymdownx.details
  - pymdownx.superfences

plugins:
  - search
  - callouts:
      aliases: true  # Enable/disable alias support (default: true)
      breakless_lists: true  # Enable/disable breakless list support (default: true)
      title_from_first_bold: false  # Use the first lone bold content as the title (default: false)

Note: If you have no plugins entry in your config file yet, you'll likely also want to add the search plugin. MkDocs enables it by default if there is no plugins entry set, but now you have to enable it explicitly.

Usage

mkdocs-callouts converts the following:

> [!INFO] Title
> An information callout from Obsidian
> inspired by the syntax from the Microsoft Docs

and turns it into:

!!! info "Title"
    An admonition block for MkDocs.
    Allowing you to edit your notes
    with confidence using Obsidian.

Foldable blocks

Foldable blocks are also supported. (> [!INFO]- Foldable closed by default, > [!INFO]+ Foldable open by default)

Inline blocks

To turn a callout block into an inline block you can use the |left or |right syntax in the type notation like so:

> [!INFO|left] -> !!! info inline (alt: [!INFO | left])
> [!INFO|inline] -> !!! info inline

> [!INFO|right] -> !!! info inline end 
> [!INFO|inline end] -> !!! info inline end

The following also works, but Obsidian may not render the block type correctly.

> [!INFO inline] --> !!! info inline
> [!INFO inline end] --> !!! info inline end

To get more information about inline blocks, or how to add your own custom callout blocks, check the Material Mkdocs Documentation.

Aliases

Obsidian allows the use of aliases when creating callouts, mkdocs-callouts converts these to the corresponding block type. Should you wish to disable this behaviour then you can do so by setting aliases to false in the plugin configuration:

plugins:
  - search
  - callouts:
      aliases: false

Breakless lists

Markdown specification requires a blank line between list items and other block elements, whereas Obsidian does not require this. This plugin will by default automatically add a blank line between list items and callout blocks (if none are present). Should you wish to disable this behaviour then you can do so by setting breakless_lists to false in the plugin configuration:

plugins:
  - search
  - callouts:
      breakless_lists: false

First bold line as title

If the first line of a callout block is in bold, it can be used as the title for the admonition block. To enable this behaviour, set first_bold_as_title to true in the plugin configuration. Behavior is disabled by default, see #34

> [!INFO]
> **This is the title**
> This is the content of the callout block.

Will render as:

!!! info "This is the title"
    This is the content of the callout block.

plugins:
  - search
  - callouts:
      title_from_first_bold: true