markdown-callouts#
Extension for Python-Markdown: a classier syntax for admonitions and collapsible blocks
Installation#
pip install markdown-callouts
-
If using MkDocs, enable the extension in mkdocs.yml:
markdown_extensions: - callouts -
If using Python-Markdown in some other way, see its reference. You can add this extension to the list of plugins:
- as a string:
'callouts' - as an object:
from markdown_callouts import CalloutsExtension
- as a string:
The extension is configurable as such:
strip_period(defaulttrue) - whether to strip the final period from custom titles syntax.
Usage#
This adds a new block-level syntax to Markdown, to put a paragraph of text into a block that's specially highlighted and set apart from the rest of the text.
The syntax is: as the start of a paragraph, write a word in all capital letters, followed by a colon and a space. Then the rest of the text in that block will be used as the body of the "callout".
For example, to get this (using mkdocs-material theme):
Note
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
| Write this Markdown with the "callouts" extension: |
|
| Rather than this (with the "admonition" extension): |
|
The titular word of the callout, transformed from all-caps to just capitalized, becomes the title for the set-apart text.
Custom titles#
If you don't like the deduced title text, you can specify a title of your own, after the all-caps word. For purposes of graceful degradation, the syntax is exactly as if you wrote one sentence emphasized in bold at the start of the callout.
For example, to get this:
Writing custom titles
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
| Write this Markdown with the "callouts" extension: |
|
| Rather than this (with the "admonition" extension): |
|
The linebreak after the title is optional. And it can be an actual linebreak with two spaces at the end of the line as well -- that has no effect on the output, but again can be relevant for graceful degradation.
About the period at the end of the sentence
The period at the end of the sentence is always dropped from the final title. You are encouraged to write those periods anyway, because when using a "vanilla" renderer, the output will look weird.
NOTE: **A few more thoughts** Lorem ipsum dolor sit amet, consectetur adipiscing elit.
NOTE: **A few more thoughts.** Lorem ipsum dolor sit amet, consectetur adipiscing elit.
A few more thoughts
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
A few more thoughts
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
A few more thoughts
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
A few more thoughts
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
If you want to keep the period in the title, you can escape it with a backslash.
And to always keep periods in the titles, configure the extension with strip_period: false.
Collapsible blocks#
(See first: Block-level syntax)
To get the following collapsed <details> block, just add a question mark right after the blockquote symbol:
Click me to read more
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod nulla.
Curabitur feugiat, tortor non consequat finibus, justo purus auctor massa, nec semper lorem quam in massa.
| Write this Markdown with the "callouts" extension: |
|
| Rather than this (with the "details" extension): |
|
The block can alternatively be initially open. Just write >! instead of >?.
Output#
The produced HTML is the same with both extensions that this replaces:
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.</p>
</div>
<details class="note">
<summary>Note</summary>
<p>Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nulla et euismod
nulla. Curabitur feugiat, tortor non consequat finibus, justo purus auctor
massa, nec semper lorem quam in massa.</p>
</details>
You may notice that the HTML contains no explicit styling whatsoever. That is because that's supposed to be handled through CSS that accompanies it. In case of MkDocs, that's handled by themes -- if they choose to support styling for the classes .admonition, .admonition-title or the tags details, summary.
In addition to the always-present class admonition, another CSS class will be added that is equal to the title of the "callout", in lowercase. The stylesheet can then choose to specially distinguish the style for a few select identifiers out of those. (Example theme)
Syntax details#
At the start of a block, there needs to be a word in all English capital letters, followed by a colon, space, then other text.
Previous block will not be picked up.
EXAMPLE: This text
is all part of a single
*admonition* block.
Next block will not be picked up.
Previous block will not be picked up.
Example
This text is all part of a single admonition block.
Next block will not be picked up.
<p>Previous block will not be picked up.</p>
<div class="admonition example">
<p class="admonition-title">Example</p>
<p>This text
is all part of a single
<em>admonition</em> block.</p>
</div>
<p>Next block will not be picked up.</p>
Inline Markdown (links, italics, etc.) is handled normally for the rest of the text. Block-level Markdown (lists, quotes, etc.) is not allowed.
The space after the colon can instead be a newline as well.
Block-level syntax#
To allow putting multiple paragraphs into the same callout and enable all of Markdown features, use the block-level syntax, which works the same as a blockquote, but with the mandatory all-caps word at the beginning of it:
> EXAMPLE: Hello world!
>
> * Item 1
> * Item 2
>
> Still going...
Next block will not be picked up.
Example
Hello world!
- Item 1
- Item 2
Still going...
Next block will not be picked up.
<div class="admonition example">
<p class="admonition-title">Example</p>
<p>Hello world!</p>
<ul>
<li>Item 1</li>
<li>Item 2</li>
</ul>
<p>Still going...</p>
</div>
<p>Next block will not be picked up.</p>
The fact that we used blockquote syntax doesn't mean any actual blockquote is involved, this is still just an admonition. We are just making a clear delineation for the block, but otherwise the angle quotes are discarded.
However... if you'll also be viewing the same Markdown through a renderer that doesn't support this special syntax, it will indeed be a blockquote -- that is also graceful degradation.
Compare this to the Admonition extension
!!! example
Hello world!
* Item 1
* Item 2
Still going...
Next block will not be picked up.
!!! example Hello world!
* Item 1
* Item 2
Still going...
Next block will not be picked up.
You can find more examples (particularly how edge cases are handled) in the test cases directory.
Collapsible block syntax#
Collapsible block syntax is a simple extension of the block syntax.
Instead of opening the blockquote with >:
- write
>?to get a<details>tag; - write
>!to get a<details open>tag.
To allow putting multiple paragraphs into the same callout and enable all of Markdown features, use the block-level syntax, which works the same as a blockquote, but with the mandatory all-caps word at the beginning of it:
>? EXAMPLE: Hello world!
>
> * Item 1
> * Item 2
>
> Still going...
Next block will not be picked up.
Example
Hello world!
- Item 1
- Item 2
Still going...
Next block will not be picked up.
<details class="example">
<summary>Example</summary>
<p>Hello world!</p>
<ul>
<li>Item 1</li>
<li>Item 2</li>
</ul>
<p>Still going...</p>
</details>
You can find more examples (particularly how edge cases are handled) in the test cases directory.
Custom titles#
A callout block with a custom title is just an extension of the base syntax, where after the capital word and a colon, the first item of the main body must be in bold. This **strong emphasis** syntax (or also with __) is directly used as the delimitation for the title, according to normal rules of how Markdown handles it. The actual <strong> tag will be excluded from the output and its contents will be moved from the paragraph and become the title instead. You can use any inline Markdown formatting within that main delimiter, and that will be preserved. Single newlines are allowed within the delimited title part, again as per normal Markdown rules.
You can find more examples (particularly how edge cases are handled) in the test cases directory.
Avoiding callouts syntax#
There are several ways of avoiding triggering the "callouts" syntax, in case you actually want to just write a word in all-capital letters followed by a colon.
In that case, precede the line with one space (which will not be represented in the final HTML):
EXAMPLE: Hi.
And if you happen to need to start your callout with a sentence in bold (without picking it up as the title), make sure to put a newline first:
NOTE: **This is a title.** Body.
NOTE:
**Not a title actually.** Body.
This is a title
Body.
Note
Not a title actually. Body.
Further features#
Custom look#
As mentioned, styling is handled through CSS, not from the extension itself. And in CSS, you can indeed completely re-define the look for each particular keyword. Adding a new keyword requires no action, other than possibly adding CSS for it.
This is well documented for mkdocs-material theme. And see another example for inspiration: Source → Result
Project goals#
The goal of this project is to support the same features as the admonition extension, under an alternate syntax that allows for graceful degradation (you can search for mentions of that on this page). That means that the page can be previewed in a "vanilla" Markdown renderer and still look fully legible, though missing some styling. That can be useful to keep your documents nicely viewable on Web source hosting such as GitHub even if that won't be your primary hosting.