search

executablebooks / markdown-it-docutils

A markdown-it plugin for implementing docutils style roles/directives.
https://executablebooks.github.io/markdown-it-docutils/
MIT License
12 stars 9 forks source link

Roles in arguments are not properly parsed #29

Open rowanc1 opened 2 years ago

rowanc1 commented 2 years ago

Leaving this as an issue here to look into in a bit. @chrisjsewell if you have ideas in that part of the code base as to why I would love to hear them!

For example, this does not parse in an admonition.

```{admonition} A **bold**{sup}`2` admonition *title*
Here is an admonition!
rowanc1 commented 2 years ago

I think this may actually be any ` in the admonition title.

rowanc1 commented 2 years ago

This does work in sphinx, so I think we should support it!

This: image

Becomes: image

rowanc1 commented 2 years ago

@chrisjsewell do you have some guidance on this? It looks like the "fence" pass does not pick these up if there is a ` in the argument area of a directive. Both a problem in python/js implementations.

fwkoch commented 2 years ago

This restriction goes all the way back to fence parsing in markdown-it and commonmark - https://github.com/markdown-it/markdown-it/blob/df4607f1d4d4be7fdc32e71c04109aea8cc373fa/lib/rules_block/fence.js#L34-L38

This isn't a problem if tildes are used for the fence, e.g.

~~~{admonition} A **bold**{sup}`2` admonition *title*
Here is an admonition!
~~~

So we could constrain the MyST spec to just using those for directives.

Somehow changing the fence parsing logic is also possible, but that would be a deep change with significant implications...

rowanc1 commented 2 years ago

The other alternative now exposed is to use colon fences, which don't fight as hard with some auto-formatting rules!

image