You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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.
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
The text was updated successfully, but these errors were encountered:
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
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
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# heading
s 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.
myst_title_is_superordinate_header
which would only act whenmyst_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
The text was updated successfully, but these errors were encountered: