Support for rST-style Admonitions

[toonetown]

It would be helpful to be able to define rST-style Admonitions using MultiMarkdown. I would suggest supporting the same format that is supported by Python Markdown (see https://pythonhosted.org/Markdown/extensions/admonition.html).

Basically, the following Markdown:

!!! note
    You should note that the title will be automatically capitalized.

Will render the following html:

<div class="admonition note">
<p class="admonition-title">Note</p>
<p>You should note that the title will be automatically capitalized.</p>
</div>

Seems like it would be a nice addition.

[fletcher]

Thanks for writing in with your suggestion. I always appreciate them, even if I don't implement them.

I don't think this feature is a good fit for MMD, for the following reasons:

1. I don't think this is useful to the vast majority of MMD users. In 10+ years, I've never needed it, for example. I get that it may be the most important thing in the world to you, but it's not a key feature for users as a whole.
2. It's really just a variant of the "allow user to specify a css class for a paragraph" feature (which is included in some Markdown variants, but is a feature I've never been particularly impressed by. I get why it's useful to some, but philosophically, it doesn't fit.)
3. It doesn't really have any meaning that is consistently recognized across document formats (e.g. HTML, RTF, LaTeX, etc.). The closest I can imagine is bold/strong, in which case just use bold/strong.

F-

[toonetown]

I actually was writing this for some feedback - it is something that I would be willing to implement if it would be a welcome addition (which it sounds like it may not be - and that's fine). As I read back to my original comments, I see that my intent was not very clear.

My main reason for suggesting it is that there is actually quite a common use case when writing documents, and articles to create "callout", "note", "warning" or other "admonition" boxes. These boxes commonly have a single title bar and a body, generally include an icon (which can be achieved in CSS), and are usually a separate color from the rest of the document (also achievable in CSS).

You can see some examples of these callout at http://www.toonetown.com/projects/admonitions.html

Especially when writing documentation, these are a very common construct - and I feel that it fits with the stated purpose of Markdown:

Markdown’s syntax is intended for one purpose: to be used as a format for writing for the web.

It can be achieved by using inline HTML, and it can also be achieved in LaTeX using (among others) the mdframed package.

I've tried to go the route of using a single column table - but that really only works if you only have a single paragraph for the body. Other alternatives I've looked at have been to use definition lists or nested block quotes - and those are workable...but it seems like forcing a square peg into a round hole. It just doesn't seem as readable.

Inline HTML version:

The main issue with defining this inline in HTML is that it is pretty verbose, and requires that you pull back the indent on the body of the the dialog (which, personally, I think looks ugly). This would basically be the output of the MultiMarkdown processor, however:

<div class="admonition note" markdown=1>
  <div class="title" markdown=1>Please note...</div>
  <div class="body" markdown=1>

This is something to note - It is separate from the rest of the document

It can contain multiple paragaphs and other markdown things, such as:

 - Lists
 - Inline <b>HTML</b>
 - etc.

It's pretty helpful

  </div>
</div>

In that example, the "note" class can be changed to get different "types" of admonitions (with different colors, icons, etc) - the recommendations from rST are:

• attention
• caution
• danger
• error
• hint
• important
• note
• tip
• warning

Definition List alternative:

This is perhaps the best alternative - although, it kind of borders on "overloading" the purpose of a definition list (though I can see the argument that it actually IS a definition list). There is not really a good way to style these boxes differently from other definition lists - or to set the "class" ("note", "warning", "important", etc) on the admonition without wrapping it in some other element (which is possible - but just adds to the verbosity of the markdown document...remember it should be readable):

Please note...
:   This is something to note - It is separate from the rest of the document

    It can contain multiple paragaphs and other markdown things, such as:

     - Lists
     - Inline <b>HTML</b>
     - etc.

     It's pretty helpful

Table alternative:

The main limitation of this alternative is the fact that you can't do multiple lines in the cell body. I do like how it is visually represented in the markdown document - because it is indicative of how it is generally rendered. It also suffers from the same "styling" limitations as the Definition List version (i.e. you can't style it differently from other tables in your document):

| Please note...                                                                                      |
| --------------------------------------------------------------------------------------------------- |
| This is something to note - It is separate from the rest of the document.  It *CAN* contain markup, |
| but separate lines are in separate cells                                                            |

Blockquote alternative:

I like how this one renders using vanilla MultiMarkdown (as a separate "box", visually) - however, it is the least readable (in my opinion) of the three alternatives in "pure" markdown form. It also has the same styling limitations as the other alternatives:

>> Please note...
>
> This is something to note - It is separate from the rest of the document
>         
> It can contain multiple paragaphs and other markdown things, such as:
>         
>  - Lists
>  - Inline <b>HTML</b>
>  - etc.
> 
> It's pretty helpful

Suggested syntax:

The syntax I originally suggested was to maintain interoperability with Python's Markdown processor extension. However, as I have been looking into this, I would actually suggest just adding the ability to set a class on definition lists. For example:

{note} Please note...
:   This is something to note - It is separate from the rest of the document

    It can contain multiple paragaphs and other markdown things, such as:

     - Lists
     - Inline <b>HTML</b>
     - etc.

     It's pretty helpful

If you leave off the title ("Please note..." in this example), then the "class" itself is capitalized and used as the title. For example, this version is identical to the above, except for the title of the admonition will be "Note":

{note}
:   This is something to note - It is separate from the rest of the document

    It can contain multiple paragaphs and other markdown things, such as:

     - Lists
     - Inline <b>HTML</b>
     - etc.

     It's pretty helpful

I understand that the same thing can be "reasonably" achieved by just using definition lists and a wrapper div (line spacing is required around the list):

<div class="admonition note">

Note
:   This is something that you should be aware of

</div>

However, doing this loses some of the simplicity and readability for these types of callouts. For example:

{note}
:   This is something that you should be aware of

is a lot easier to read - and would generate the following output:

<dl class="admonition note">
<dt>Note</dt>
<dd>This is something that you should be aware of</dd>
</dl>

The "wrapped" alternative is not terrible - but just adding this ability to definition lists would be very helpful. It also has the benefit of being backwards compatible with previous versions of MultiMarkdown. The above code is just rendered as a standard definition list with a definition term of "{note}".

Do you happen to have any further suggestions/improvements? Or is this just a complete non-starter? As I said before, I am completely willing to work on doing the actual implementation...this was meant to start a conversation, rather than be a demand for free development work.