Markdown heading levels incorrect

[jameshadfield]

First noticed in nextstrain/docs.nextstrain.org#113 (comment):

In a markdown document, the number of # characters doesn't correspond to the HTML heading level.

For instance, in the above PR the main title is ## How data... but rendered as <h1>. Other headings are ##### [a1] Colorings but rendered as <h3>.

I presume this is addressed in this repo, but perhaps not?

[tsibley]

Sphinx doesn't directly translate Markdown to rST as doing so would violate the richer (and stricter) semantics of headings that rST has compared to HTML. The first heading becomes the document title (which Markdown has no syntax for) and sets the ## offset for the rest of the section headings. So in your example:

• ## becomes a title
• ### becomes # or an h1 (first-level heading)
• #### becomes ## or an h2
• ##### becomes ### or an h3
• etc.

Was there a reason you were aiming for specific, absolute heading levels instead of semantic, relative headings levels? e.g. why did you want ##### [a1] Colorings to be an h5 instead of h3?

Also, I'd really recommend writing new doc in rST instead of Markdown, as a lot of the power and usefulness of Sphinx lies in being able to use the richer markup language. The current Markdown support in our docs is to help ease the transition to Sphinx for existing documents, not be a long-term format for documents of any appreciable complexity.

(If we really wanted to support richer Markdown in Sphinx, we'd want to use MyST instead, a quite-diverged variant of Markdown that folds in ideas from rST. But in my experience, it's diverged enough that the simplicity of Markdown is lost and it's easier to just use rST. IMO, Markdown is great for simple standalone documents, but not great for more complex document systems.)