Support for reStructuredText's admonitions

[slig]

Hi,

I needed these kind of warning in my project:

Here is the rst syntax.

And here's how I did:

!!! note "Did you know?"
    Here is a first paragraph

    1. first item
    2. second item

Which outputs:

<div class="admonition note">
    <p class="admonition-title">Did you know?</p>
    <p>Here is a first paragraph</p>
    <ol>
        <li>first item</li>
        <li>second item</li>
    </ol>
</div>

Here's my implementation https://gist.github.com/3487734. I'm not sure it fits the scope of python-markdown, but if it does, I can clean the code, write tests, docs and make a pull-request.

[waylan]

Awesome!. I've actually had a draft proposal of syntax for such an extension in my Dropbox account for some time. I just copied it over to a Gist for your review. The encouraging thing is your implementation is almost exactly like my proposal.

I only used a single exclamation point, but I think I like 3 better. That ensures less false matches and more clearly defines special syntax to the newcomer reading a source document.

I see your implementation handles admonition titles a little different. Not sure which way I like better. Will have to play with yours when I have the time. But, hey, a working implementation is better than a proposal. I just haven't had the time to actually implement mine yet.

One other thing, I'm not sure that this belongs in the markdown library. I'm not aware of any other markdown implementations that support such a feature and the more extensions we include, the more of a maintenance burden this becomes for Python-Markdown. Perhaps it should be packaged separately and listed with the other third party extensions - at least for now. If it becomes popular, we can always reconsider later.

[waylan]

Oh, I just remembered what my motivation was for writing my proposal. I actually wanted this feature when rewriting Python-Markdown's documentation. If we are going to use it in the docs, then I think we will probably want it included with the library. Maybe I will include it after all. I'll let you know for sure once I get a chance to play with it.

[slig]

Great! I couldn't find anything like this for markdown and that's why I thought it might be out of scope.

I used 3 exclamations points (plus a space) so everything is aligned with a tab_length = 4.

About the titles and CSS class, I wanted to avoid duplication. In my project, for instance, most of the time I'll write:

!!! note

to get:

<p class="admonition-title">Note</p>

but sometimes, depending on the context, a "Did you know?" will look better.

Also, my project isn't in English, but the codebase (and CSS classes) is, so we can do:

!!! atencao

and get:

<p class="admonition-warning">Atenção</p>

So that is my motivation for that config.

I'm obviously open to suggestions/improvements about the code in any aspect. I'll wait for answer (after you play with it). Thanks for your time!

[waylan]

I like what you've done. Go ahead and package it up as a pull request
(with docs and tests) and I'll merge it in. This is nice work. I really
like the syntax you devised.

[waylan]

I'm closing this as a duplicate of pull request #140.