search

executablebooks / mystmd

Command line tools for working with MyST Markdown.
https://mystmd.org/guide
MIT License
172 stars 50 forks source link

Compatibility with RST Glossaries #618

Open rowanc1 opened 9 months ago

rowanc1 commented 9 months ago

We should add compatibility with Sphinx/RST glossaries (which are based around indentation). At the very least the compatibility warning should be improved with a link to how to do this in Sphinx.

See https://github.com/executablebooks/MyST-NB/issues/544#issuecomment-1734574664

agoose77 commented 3 months ago

I suspect there will be more than one instance of places that we want to break Sphinx compatibility for strictness. I wonder whether we should introduce compatibility, but hide it behind a feature flag. The idea would be that jupyter-book could enable this flag, but MyST-md would have no need of it.

Then again, jupyter-book would probably just define a custom high-priority transform that normalises the glossary.

Which of the two do you prefer?

rowanc1 commented 3 months ago

Yes, I like doing this via a flag, and having pre-defined configs for different compatibility stories (e.g. sphinx, quarto, etc.).

The was I had played out the development of this is to look at the parsed body content in the directive, if it has definition lists, then it is the new format, if not, parsing that based on the body's raw text in the directive, and calling the parse function after splitting on new lines. The outcome of this directives run function would then always be a defList.

agoose77 commented 3 months ago

The was I had played out the development of this is to look at the parsed body content in the directive,

I had the same thought! I like the idea of gating that behind a feature flag so that we can have a "strict" parser for core MyST, but more liberal for JB.