@tqchen thanks for the context. I agree that it may not be worth it if you still have to learn restructuredtext to write a single document. with that said, I do think that MyST-Parser seems to be an improvement over recommonmark.
There is also some more context on why MyST-Parser was created. It does seem that they intend to support more of the functionality of restructuredtext and there is more support for extensions.
I agree that it’s not optimal to write non-tutorials in markdown and tutorials in rst. sphinx-gallery appears to be adding support for MyST-Parser, so perhaps when that lands, it could be a good time to reconsider this.
That said, I do think the bar here should be: would the community find it easier to write docs if we support markdown? We have a lot more docs that we need to write.
The markdown parser was OK for certain components but still do not allow us to obtain the best control of the structure component. MySt likely will have a similar problems we faced before.
@tqchen could you elaborate on this point, even if just for historical record? would be great to understand which features myst-parser would need to support to overcome past problems.