! Note
This is a paragraph in a "Note"
This is a second paragraph.
! Warning
This has not been implemented. This is only a demonstration of the syntax.
! Attention
* Any block level text can be nested.
* Like this list.
Unlike Sphinx, this will allow any term on the "! Admonition" line. However, the text must only be one line with no blank line after it and that text will be used as the title for the box. The remaining blocks will be the body of the box. If the title is only one word, then that word (in lowercase) will be assigned as a class on the div.
Thus the above examples would output the following html:
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This is a paragraph in a "Note"</p>
<p>This is a second paragraph.</p>
</div>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This has not been implemented. This is only a demonstration of the syntax.</p>
</div>
<div class="admonition attention">
<p class="admonition-title">Attention</p>
<ul>
<li>Any block level text can be nested.</li>
<li>Like this list.</li>
</ul>
</div>
And for a multi-word title:
! Multi-Word Title
No special class for this one.
<div class="admonition">
<p class="admonition-title">Multi-Word Title</p>
<p>No special class for this one.</p>
</div>
We could just special case known specific words (note, warning, attention, ...), but by allowing any one-word title to get a special class, we support other languages. Granted the css needs to account for those languages as well, but Markdown need not concern itself with that. However, by only allowing one-word titles to get special treatment, it significantly reduces the possabilities any css may need to account for while still leaving a lot of flexability.
Here's notes on existing implementations:
In Sphinx, the resulting output looks like this:
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p class="last">This is a paragraph.</p>
</div>
This is what plain Rest outputs with two paragraphs:
<div class="note">
<p class="first admonition-title">Note</p>
<p>First paragraph</p>
<p class="last">Second paragraph</p>
</div>
The Rest docs provide more info.
I am not including the "first" and "last" classes as they only make sense when
you are only accepting paragraphs as children of the div (i.e, in my third example,
does the <ul> get the class "last" or the last <li> of the <ul>?). Besides,
you can get access to "first" and "last" children in css (in modern browsers)
without the classes anyway.
Also note that Rest does not allow a blank line between title and body. As definition lists already work this way in Markdown, it makes sense to copy that behavior here as well.
See an implementation of a similar proposal here.