compatible headings - MD to docx & html (multiple h1)

[KOTRET]

Hi there!
I'm having trouble to decide for a proper MD-structure in order to convert it to docx and html

I am using markdown in order to document my work. The documents are structured with headings, all topmost headings begin with #.
Example, just a compressed excerpt:

---
title: "my document title"
---

[[_TOC_]]

# preface
## purpose
## history

# API description
## endpoint 1
### parameters
## endpoint 2
…
# usage
…

The logical structure expresses the sections of the article and (imo) is perfectly valid.
When converting to docx, the headings are at the proper level and the styles are applied correctly - everything is fine.

To embed the same md as html, I'm using Parsedown and adjusted it a bit in order to render the toc.
In the output, the #… are replaced with h+ the number of # (similar to pandoc).
The result is a document, which contains several <h1> elements (for each main heading).

Since web-developer is not my primary job, I was not aware about problems this could cause when it comes to screenreaders and document outlining. This came up after Markdownlint complained about multiple level 1-headers. I've read several articles about this:

• https://www.a11yproject.com/posts/how-to-accessible-heading-structure/#one-h1
• https://webdesign.tutsplus.com/the-truth-about-multiple-h1-tags-in-the-html5-era--webdesign-16824a
• https://html5doctor.com/computer-says-no-to-html5-document-outline/
• https://html.spec.whatwg.org/multipage/sections.html#sample-outlines

This more or less led me to the conclusion, that using multiple <h1> is discouraged in this case.
At the same time this would mean, that - when indenting "properly" - the wiki-article converted from md would have only one top-level heading, which not only feels very awkward, but indenting with an additional # leads to incorrect docx.

I guess the easiest solution would be to adjust the MD-parser in order to indent the headings one more level for html,
what are your thoughts about this?

[jgm]

See the manual on --shift-heading-level=1.
As the manual says,

--shift-heading-level-by=1 may be a good choice for converting Markdown documents that use level-1 headings for sections to HTML, since pandoc uses a level-1 heading to render the document title.

[KOTRET]

Thank you, I've totally overlooked that option, that is a good hint!
As I'm using parsedown, this approach won't help that much in this case, except to see that someone stumbled upon this before and there is an option =)
Struggeling with the missing title though, but i guess this can be handled by adjusting parsedown.

The question itself was more general, I'm wondering how others handle this problem and generating documents (docx/pdf and html) out of a md-wiki.