Add support for rendering admonitions using "markdown friendly" syntax

[chrisjsewell]

i.e. implement an extension in markdown-it-py to encapsulate something like pandoc fenced divs

:::{note}
my note
:::

or suggested in jupyter jupyter/notebook#1292 (comment)

!!! note
    This is a note.

Then render it here

[choldgraf]

I suppose this could be an extension that others can activate out of the box, but I'm a little hesitant to include this in default behavior. It'll mean we have two ways of doing the exact same thing ("There should be one-- and preferably only one --obvious way to do it.")

What's the reason why we would recommend people use this syntax over ``` syntax? Compatibility with pandoc?

I think one way to keep this clean is to create a different package that is a plugin for this one, and have a system that allows you to activate these plugins in a way that the myst-parser knows how to use. That way people could include other markdown extensions as well.

[akhmerov]

I'd like to chip in here. My main problem with admonitions as they are now is not so much their syntax, but rather what they offer in sphinx out of the box. Specifically, the specialized ones (warning/error/note) offer a pre-defined style, but do not allow to tweak the title. Further none of them are be collapsible.

I have used the !!!/??? syntax via mkdocs, but I don't think it has a big advantage over a directive (since MyST has directives, yay).

One of the items on my todo list in converting my mkdocs list to jupyter-book is to override all sphinx admonitions, and cook something together using sphinx-panels instead. Perhaps this is also something to consider more generally.

[choldgraf]

re: admonitions, we actually implemented the following option in the pydata-sphinx-theme (and thus in jupyter book)

```{admonition} My title
:class: warning
My body
```

see the last example here: https://pydata-sphinx-theme.readthedocs.io/en/latest/demo/demo.html#admonitions

it's not documented because I'm not sure if it's a good idea or not haha, do you think it's a good idea?

[akhmerov]

Don't know if it's a good idea, but I'll 100% use it. Now if only they also had a collapsible version that rendered like the dropdown from sphinx-panels...

[chrisjsewell]

Well yeh that "option" (I'd more just say that you fixed the CSS 😛 ) is also available with the RTD theme. Anyway that's the approach I used in this page, plus adding custom icons and funky sphinx panels stuff: https://aiida.readthedocs.io/projects/aiida-core/en/latest/intro/get_started.html

[choldgraf]

@chrisjsewell lol that's a good point, we actually changed this behavior to be more generic and now I realized that it's generic enough that is no longer pydata-sphinx-theme-specific haha

[chrisjsewell]

Now if only they also had a collapsible version that rendered like the dropdown from sphinx-panels...

well I guess that's just a matter of playing around some more with the CSS 😄

anyway, for the admonitions: the point was:

What's the reason why we would recommend people use this syntax over ``` syntax?

As we've discussed previously, to placate the people that want myst to be rendered by Jupyter better "out-of the-box", i.e.

:::note
Here *nested* syntax will **render** within a general markdown viewer.
:::

:::note
Here nested syntax will render within a general markdown viewer.
:::

```note
Here it  *is* just **shown** as is
```

Here it  *is* just **shown** as is

different package that is a plugin for this one, and have a system that allows you to activate these plugins

We already have that; its called markdown-it-py!

[choldgraf]

As we've discussed previously, to placate the people that want myst to be rendered by Jupyter better "out-of the-box"

makes sense 👍 do we see any reason that we'd want these two syntaxes to behave differently?

We already have that; its called markdown-it-py

so then the plugin would be defined inside markdown-it-py and then we could let people activate that plugin in the same way that they'd, say, activate the [] symbols for math?

[chrisjsewell]

Yep the same way that #132 and #153 will be optionally activated, by making this more configurable:

MyST-Parser/myst_parser/main.py

Lines 31 to 45 in 8dda2f7

	md = (
	MarkdownIt("commonmark", renderer_cls=renderer_cls)
	.enable("table")
	.use(front_matter_plugin)
	.use(myst_block_plugin)
	.use(myst_role_plugin)
	.use(texmath_plugin, delimiters=math_delimiters)
	.use(footnote_plugin)
	.disable("footnote_inline")
	# disable this for now, because it need a new implementation in the renderer
	.disable("footnote_tail")
	# we don't want to yet remove un-referenced, because they may be referenced
	# in admonition type directives
	# so we do our own post processing
	)

[choldgraf]

Another quick thought here as I was playing around with writing this kind of syntax. If we support :::, then we probably don't need the {curly-brackets} in that case. E.g. treat:

```{this}
```

equivalent to

:::this
:::

since we are not over-riding any other behavior with it.

I think other than that difference, the two patterns should behave exactly the same way. E.g. you could do

```{admonition} My title
:key: val
Content
```

and

:::admonition My title
:key: val
Content
:::

The one downside I can see there is that there isn't an obvious separation between the directive name and its arguments

[rowanc1]

Question about the "notes require no inputs, so they can be on the same line". For example:

```{note} Notes require **no** arguments, so content can start here.
```

This seems a bit different than commonmark, which would ignore the paragraph (and not show up in most MD renderers). For example, in github that is rendered as a blank box :(:

Also, it seems more like the title "defaults" to Note, and perhaps you should be able to override it? For example:

```{warning} Custom Warning Title
This is my body text.
```

I am currently playing with the implementation using markdown-it-container and we will have to do some hacks to get a single "info" line of a container to turn into an inline paragraph.

[choldgraf]

you are describing things that I wish existed in Sphinx but they don't :-)

This is a really annoying quirk of reStructuredText / docutils - basically, the argument just after the directive name could be parsed as an argument. But, if that directive doesn't accept arguments, then the text in that location will instead be parsed as content for the directive. So that's what you can do:

```{note} First line of my content
second line of my content
```

and you can also do

```{admonition} My admonition title
First line of my content
Second line of my content
```

[rowanc1]

Could we not bypass that for the markdown parser to make it more sensible and more in line with commonmark (which ignores the first line as "info")?

There could be post processing on the syntax coming out of the markdown parser that changes "notes with a title" to "admonition with a class and a title". This could be done before passing off to sphinx, perhaps?

[chrisjsewell]

Yes for general directives this is a logical convention "imposed" by docutils and required by some extensions (e.g. sphinx tabs).
But, for this additional, specialised syntax, there's no necessity to stick to it; the first line can just be for the directive type/argument.

As @choldgraf mentioned, to create adminitions with specific heading, you would use:

```{admonition} My admonition title
:class: warning other

Content
```

note here I add one or more classes: most HTML themes use the class, identical to the name of the admonition, to format the admonition box, via css (or you can always add custom css). So this would look the same as the warning directive, but with a different title.

As mentioned previously, this necessitates the ability for the syntax to capture additional data to the directive type and title.
You could for example use something like:

:::{class1,class2,class3} My title
content
:::

This is simple and would work for all admonitions. However, the down-side is that it would not generalise to e.g. figures where you need to capture more than just the class option