Add syntax for admonition blocks.

[drrosa]

At the moment, embedding reST using eva_rst is the only way to render admonition blocks. It would be great to have a better syntax for admonition blocks that allows the content of admonitions to be written in Markdown and fall back reasonably on GitHub.

[noahtren]

!!! note seems like a pretty popular extension to Markdown for doing admonitions. See jupyter/notebook#1292 (comment)

It would be great if recommonmark supported this.

[noahtren]

AutoStructify recommends this syntax, but it doesn't seem to work if you want an admonition with multiple lines or extra markdown formatting:

``` important:: Its a note! in markdown!
```

[choldgraf]

Dug into this a little bit today, just to give some extra information that I think is relevant:

The bits that over-load code cell syntax and convert them to directive syntax is in the AutoStructify module: https://github.com/readthedocs/recommonmark/blob/master/recommonmark/transform.py#L15

Specifically, the auto_code_block method uses a regex to detect in the language has the :: syntax that is characteristic of a directive, and if so then it runs the contents of the block as a directive (https://github.com/readthedocs/recommonmark/blob/master/recommonmark/transform.py#L254). I think the issue with no multi-line syntax being supported is somewhere around here: https://github.com/readthedocs/recommonmark/blob/master/recommonmark/transform.py#L258

The other issue with that is that it's using an instance of the docutils Parser to parse the contents of the directive block, and that parser will assume that the contents are in reStructuredText rather than markdown, so you can't do things like:

```note:: this [is a link](mylink.com)

It also feels relevant that the state machine used in the transform for AutoStructify is the DummyStateMachine (https://github.com/readthedocs/recommonmark/blob/master/recommonmark/transform.py#L329). Perhaps that could be overloaded to use a markdown parser instead of an rST one, at least in the parts that are running a directive directly from the state maching (e.g. https://github.com/readthedocs/recommonmark/blob/master/recommonmark/transform.py#L249)

[mlncn]

I support the syntax first proposed by noahtren:

!!! note
    This is a note.

This seems to be the default in the markdown in this space:

• python-markdown: https://python-markdown.github.io/extensions/admonition/
• mkdocs: https://squidfunk.github.io/mkdocs-material/extensions/admonition/

Could we plug in or use the python-mardown extension with recommonmark?

[chrisjsewell]

Note that nested parsing of Markdown is supported in https://myst-parser.readthedocs.io/en/latest/using/syntax.html#directives-a-block-level-extension-point (as used by jupyterbook), for admonitions and any other directive, currently as:

```{note}
This note is written in [markdown](https://example.com)
```

with potentially more markdown friendly syntax specific for admonitions to come: executablebooks/MyST-Parser#154