Option to demote other headers when title becomes header

[Anaphory]

Describe the problem/need and solution

Context

As I mentioned in #511 I would like to include the Markdown file for my JOSS submission into the Sphinx documentation of my Python package, ideally without modifications.

Problem / Idea

The JOSS structure assumes that the paper has a title, and then a number of sections that would be subordinate to the title in the document structure. MyST on the other hand assumes that a

# heading

becomes a first-level heading of the resulting document, even when myst_title_to_header=True declares that the entire document has a higher-order heading derived from the title. I would like to turn all my # headings into <h2>s in the generated documentation HTML (etc. for other sphinx output).

Solution It seems to call for a new MyST configuration option, but I don't know exactly what it should do.

1. I can imagine a general way of shifting headers by an integer, maybe even settable in the document-metadata. So when set to 1, my use case is that all # become h2 and all ## become h3, but there is nothing preventing us from allowing a -1 that would promote all ### to h2s.
2. It could be a simple boolean global config option myst_title_is_superordinate_header which would only act when myst_title_to_header=True and would do the shift only then.

I tried to have a look in the code how heading levels are implemented, but I didn't really understand it, so I don't know how invasive which option (including options I haven't considered) would be.

Benefit This might have another benefit for embedding Markdown documents that were written as standalone text in bigger documents (eg. individual papers as part of a cumulative thesis or other types of chapters in a book).

Guide for implementation

No response

Tasks and updates

No response

[chrisjsewell]

Yeh I actually found myself wanting this on https://myst-spec.readthedocs.io/en/latest/spec-cmark.html 😄

Agree, that it probably makes sense to have this as a separate global config, although maybe myst_title_is_superordinate_header is a bit long-winded lol

It should be quite easy to implement