Better description of MD vs MyST vS ReST

[rkdarst]

Describe the problem/need and solution

Context "Markdown" means so many things, I am still not happy when I have to explain MyST and its differences to people, and why you need to specifically learn Sphinx semantics to use MyST/Sphinx well. "Markdown" is used so many places and with so many different syntaxes, that unless someone is very specific about what they search, there is a big chance of getting bad advice on how to do things. I've had to explain with so many people, I would like to do it once and have something to link to.

Problem / Idea Problem: above Idea: Explain it better.

Solution I finally came up with something I thought was a good, short explanation of why one needs to pay attention to this.

	Syntax	Semantics
MD	markdown	HTML
MyST	markdown	Sphinx/docutils
ReST	restructured text	Sphinx/docutils

"and the nice parts of Sphinx come from the higher-level docutils/sphinx semantics, so you need to be able to use that. While you can use almost any regular markdown syntax you find online, your project may not be as structured as it should be."

Benefit This would benefit the people trying to use MyST because they would be able to understand existing information on Markdown/ReST (outside of MyST-specific ones) better.

Guide for implementation

It could go here: https://myst-parser.readthedocs.io/en/latest/explain/index.html ... but I would prefer if this idea was also somehow introduced at a higher level, not only hidden here. It seems like something that is said higher, but I can't find it right now.

Tasks and updates

I can write and PR it if you all think it's interesting and give any preferences on where to put it.

[chrisjsewell]

Heya, I'd note there is some "wider" efforts currently going on, around specifying MyST: https://github.com/executablebooks/myst-spec

Really, the goal is to not have it directly tied to sphinx/docutils, e.g. this is just one implementation of a MyST parser 😅

[rkdarst]

Great! And good point. I guess in some ways it makes it more complex (more different parts that connect), but maybe actually clarifies things since it forces people to think about the different layers separately, instead of mixing them together.

In my ideal world, I would make a new page on the myst-parser docs which go into the different pieces and how they fit together: syntax vs semantics, why you shouldn't write HTML-but-in-markdown, etc. Later, this could then be expanded to other parsers and consumers, and removed and put into whatever higher-level docs where it is more appropriate.

Is this any use?

(Also, side note: I really dislike how everything is called "markdown". It's not bad, but the way we have the same name for so many different things, and it is going to stay that way forever. For most markdown implementations, it doesn't matter, but for MyST+Sphinx (and presumably others), it really does matter, semantics are far more important than syntax, and "markdown" is a good marketing term for getting users, but not a good description of what people need to know to use it well - and what I would like to improve)

[chrisjsewell]

Is this any use?

I think it will be thanks... but I would maybe wait a little, until we have finalised myst-spec and worked out the organisation of documentation