Issues with MyST documentation

Here are some issues I noticed with the MyST documentation as a new user:

• The docs don’t mention anywhere how to do a table of contents. Since these are so essential in Sphinx, this seems like a major omission (as an aside, are there plans to implement something like recommonmark’s auto toc tree?).
• I think it’s a mistake to include myst_config = {"disable_syntax": ["emphasis"], "math_delimiters": "brackets"} in the getting started config. Most people will just copy-paste that config, but this is not a config most people would want to use. Rather, the getting started should list what people should copy-paste to get started, and the config options should be documented somewhere else. There is a link to https://github.com/executablebooks/markdown-it-py which claims to list the syntax elements that can be disabled but I don’t see any such list on that page.
• The instructions on how to run the benchmarks seem out of place in the “getting started” section. Why do I need to run the benchmarks to get started?
• The RST/Markdown Rosetta stone example is a good idea, but it should focus more on the source rather than the rendered pages, which appear to be identical. I would suggest inlining the sources directly in a code block, rather than having download links for them (which don’t even open in the browser). If it is possible to put them side-by-side that would be better, but I don’t know if that is easy to do.
• I had issues finding the GitHub repo but that has already been fixed.

[chrisjsewell]

I got the error before I included sphinx.ext.imgmath.

that is definitely not the case if the only extension you have loaded is myst_parser, perhaps one of the other extensions you are using is loading sphinx.ext.imgmath?

In general, it would be nice if the manual states which other extension this extension uses.

myst-parser does not use any other extensions. For math it simply translates dollarmath to the internal sphinx AST math node representation, it does not dictate in any way how it is rendered.

If you load sphinx.ext.imgmath then you will also need dvipng (as it documents), but that is not anything to-do with myst-parser

[choldgraf]

yeah I agree that we should start with the most common or most basic / intuitive use-case, and then go into more detail later on.

and re: the backticks, markdown tends to “nest” literal blocks according to the number of ticks and whitespace / newlines, so

`` `hi` `` produces `hi`

and

````
```
hi
```
````

produces

```
hi
```