MyST-Parser
MyST-Parser copied to clipboard
executablebooks
Don't be so anal about heading levels
Describe the bug
$ cat lol.md
## test
$ pandoc lol.md
<h2 id="test">test</h2>
OTOH, MyST decides to throw a huge tantrum and generates the following:
<div class="document" id="test">
<h1 class="title">test</h1>
<div class="system-message">
<p class="system-message-title">System Message: WARNING/2 (<tt class="docutils">lol.md</tt>, line 1)</p>
Document headings start at H2, not H1 [myst.header]</div>
</div>
This breaks the use-case of using MyST for document fragments to be included into other documents or templating engines.
This actually works fine for regular reStructuredText docutils. Yes rst syntax is different and the heading levels are determined implicitly by the structure of the document, but exactly for this reason docutils provides config options for the user to override the initial header level. There is also another option to control whether the first heading is considered the "title" or not, doctitle_xform.
Markdown has explicit heading levels, and therefore does not need these two options. So, MyST can and should generate <h2> etc directly, just like pandoc-Markdown does.
Reproduce the bug
As described above, with the pandoc example.
List your environment
$ myst-docutils-html --version
myst-docutils-html (Docutils 0.19.1b.dev, Python 3.10.7, on linux)
Note, merely suppressing the warning doesn't work:
- it only works via sphinx, not when using docutils directly.
- the output continues to be
<h1>not<h2>.
Dude, the title of this issue is not acceptable. But setting aside that, with the develop version of myst-parser:
myst-docutils-html lol.md --myst-suppress-warnings="myst.header" --no-doc-title --initial-header-level=2
...
<body>
<div class="document">
<div class="section" id="test">
<h2>test</h2>
</div>
</div>
</body>
</html>
Markdown has explicit heading levels, and therefore does not need these two options.
It does though, this is the AST that is generated:
$ myst-docutils-pseudoxml lol.md --myst-suppress-warnings="myst.header" --no-doc-title
<document source="test.md">
<section ids="head" names="head">
<title>
head
there is no information captured about what the "original" heading level was.
you could add this here, e.g. <section level="2" ids="head" names="head">,
but then you would also need to add code in docutils/sphinx to actually do something with this
Basically, you would need to change https://github.com/live-clones/docutils/blob/18fa34d24994d629e3887152fe17b281e20ee907/docutils/docutils/writers/_html_base.py#L1610, to set the h<i> based on node["level"]
If this is something you want, then you need to open an issue/PR in docutils for it
But setting aside that, with the develop version of myst-parser:
myst-docutils-html lol.md --myst-suppress-warnings="myst.header" --no-doc-title --initial-header-level=2... <body> <div class="document"> <div class="section" id="test"> <h2>test</h2> </div> </div> </body> </html>
I am saying that MyST should set --initial-header-level and --no-doc-title automatically when it detects that the first heading is ## not #, since the Markdown format specification uses neither of these concepts.