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 8 forks source link

every admonition should accept optional title #46

Closed tavin closed 1 year ago

tavin commented 1 year ago

Recent experiences with myst-vs-code have taught me this is necessary. Otherwise, for example, your notes are titled "Note" even though you have written

:::{note} AnythingButNote
asdf
::::

One doubt -- does optional_arguments need to be set back to zero for the plain Admonition where required_arguments = 1?

welcome[bot] commented 1 year ago

Thanks for submitting your first pull request! You are awesome! :hugs:
If you haven't done so already, check out EBP's Code of Conduct and our Contributing Guide, as this will greatly help the review process.
Welcome to the EBP community! :tada:

rowanc1 commented 1 year ago

Hey @tavin -- thanks for the PR! We are having some conversation about this behaviour as a MyST enhancement over here:

The default behaviour of docutils doesn't allow for admonition titles on named directives, which this implementation tracks a bit more closely than mystjs. There are ways to change this behaviour, in a sphinx extension for example, but it isn't the default at the moment.

tavin commented 1 year ago

Ah ok @rowanc1 I wasn't aware, thanks. I note however that in this implementation, even without my change, the optional argument is picked up and used as the admonition title IFF the directive contains a key-value parameter:

:::{note} AnythingButNote
:class: whatever

asdf
::::

I suppose this was accidental and not aligned with docutils? I am actually referring to v0.0.12 here since that's what myst-vs-code depends on. So I didn't check this behavior in any recent releases. Maybe you have fixed it.

Well I am basically now relying on a locally patched v0.0.12 and locally patched myst-vs-code to get my expected admonition behavior while authoring markdown. I hope this isn't a dead end... anyway I will take a look at your links, cheers.