Add MyST markdown example?

[mgielda]

First of all, thanks for this work and the awesome theme - looking forward to adopting it in some projects (worked for me out of the box!).

I was curious if you were aware of MyST markdown - https://myst-parser.readthedocs.io/en/latest/syntax/roles-and-directives.html - which is a nice twist given this theme's mkdocs origins. MyST markdown has the benefit of being practically a drop-in replacement for RST, except being an extension of CommonMark, which means that the syntax feels much more familiar to markdown people. The added benefit is that a JS parser exists (the key bit is here: https://github.com/executablebooks/markdown-it-docutils) so that it integrates much better than RST with the web ecosystem.

Overall I think it might be a nice idea to have a little shout-out or example of using this theme with MyST. I can confirm it works out of the box, just add the relevant extension and use an .md file.

[jbms]

Would you care to contribute an example to the documentation?

[2bndy5]

We are aware of the MyST extension, and we've had other users report positive experiences about using it in this theme.

My only main concern with adding it to the docs is that people should be aware that it isn't exactly the same MD syntax used in the mkdocs-material theme. So, some tweaking should be expected if users are migrating from mkdocs-material to sphinx-immaterial.

A PR would be appreciated.

[mgielda]

Hi @2bndy5! I assume not too many people would be interested in migrating from mkdocs to Sphinx this way, after all they would need to migrate their TOC, write a conf.py etc - tweaking the markdown itself is probably the least of their problems :)

But generally people using markdown and looking for a good documentation framework could be lured by this combination.

Sphinx is usually viewed as RST centric, so the option to use MyST markdown and get all the features (not like in the original markdown support where you'd have to let go of many of the Sphinx capabilities) would most likely be welcome.

I might be able to do a PR but most likely after we've had a chance to adopt this flow internally.

[2bndy5]

It's never good to assume things. I personally migrated a (small) project from mkdocs-material to sphinx-immaterial, but I rewrote the MD files in RST because that's just my personal preference (and it doesn't require more 3rd party Sphinx extensions).

Off the top of my head, I can think of 3 other instances of user feedback (from different users) that had questions about migrating from mkdocs-material to sphinx-immaterial; 2 of the users were documenting an API, the other user was using MyST (and just wanted to hide the toc).

[2bndy5]

Good news for those migrating: pymdownx extensions will be switching to a new "directive" oriented block syntax that mimics MyST block syntax. This means that migrating from mkdocs to sphinx (or vice-versa) should be less work with the new/proposed syntax. I'm told there will be a minimum 2 year transition away from the current "block syntax soup", then it will be moved to a legacy mkdocs plugin.

[2bndy5]

I had an idea that would evolve our rst-example directive into something that could take a MyST block and feed it through an isolated MyST parser to get the docutils/Sphinx nodes needed to render it. It would be cool if we could feed a new doc-example directive both rST & MyST blocks and show the output with content tabs. This idea is on the back burner for now, but it may be a better solution.

@mgielda Was the actual requested solution a single page of MyST examples? Or were you requesting all rST examples be additionally shown in MyST examples as well (kinda like sphinx-design docs do but prettier)?

[mgielda]

Hi @2bndy5, Depends on how all-in you want to go on MyST!

I was thinking more along the lines of having one (short) chapter in .md explaining that you can also use MyST and it just works, and potential use cases. And some (external) links to MyST syntax etc. And of course any clashes/incompatibilities we detect in this setup, hopefully 0 or few.

Basically - bringing into people's attention that you can have both Sphinx, markdown and a nice material theme, in one package. That would definitely help the MyST ecosystem and the immaterial_theme too I think.

Having to do all the pages in both RST and MD seems much more work, but of course would also be a way to go.

[2bndy5]

I was thinking more along the lines of having one (short) chapter in .md explaining that you can also use MyST and it just works, and potential use cases. And some (external) links to MyST syntax etc.

I think a simple copy-n-paste of MyST core syntax doc would suffice then. It would be nice to find a MyST equivalent to the rST primer doc that we copied from Sphinx' docs.

And of course any clashes/incompatibilities we detect in this setup, hopefully 0 or few

If something passed through the MyST parser doesn't behave well with this theme, then its likely a problem with MyST at this point. AFAIK, the MyST parser's goal is to take MD and generate an output similar to that of the docutils/Sphinx rST parser's output We can't be expected to make special exceptions for the DOM generated by MyST. The same goes for various MyST plugins as well.

One already known caveat with MyST is using sphinx.ext.autodoc ext because it is designed to pass API comments/docstrings through the rST parser only. I mention this because this is the main benefit to using sphinx over mkdocs (aside from better RTD support)

Having to do all the pages in both RST and MD seems much more work

Not all the pages, but yes, it would be lot more work. On second thought, we shouldn't auto-render any MyST examples' output (in this approach) because it may conflict with the auto-rendered output from rST examples (eg the :name: option of directives). While I think this would be the ideal approach, it would be years until fruition. It would be easier if there was a rST to MyST translator (or vice versa).

EDIT: I just found a python API that can allegedly convert rST to MyST: https://rst-to-myst.readthedocs.io/en/stable/api.html#rst_to_myst.mdformat_render.rst_to_myst