maven-site-plugin h2+ headings are ignored in md.vm files

Affected version

3.21.0 (current in maven-site)

Bug description

When writing md.vm files headings from second level on are ignored and not rendered - neither on the page nor in the TOC-macro.

From the following snipped

<!--MACRO{toc}-->

# Header 1

## Header 2

### Header 3

gets rendered to this

Workaround is some crazy

<!--MACRO{toc}-->

# Header 1

#[[##]]# Header 2

#[[###]]# Header 3

Aug 11 '25 14:08 Bukama

## is a comment in Velocity processing, not much we can do

Oct 10 '25 17:10 slachiewicz

any idea? better documentation than https://maven.apache.org/plugins/maven-site-plugin/examples/creating-content.html#common-issues-and-workarounds ? like something more prominent in https://maven.apache.org/guides/mini/guide-site.html?

Oct 10 '25 22:10 hboutemy

or any idea like hacking Doxia Renderer, that launches the Velocity template engine https://maven.apache.org/doxia/doxia-sitetools/doxia-site-renderer/ like "if source is markdown and we find ## at line start, warn" = strange hack, but that may be adapted to the situation, as I can get that the current Velocity behaviour with Markdown content feels like a bug "content strangely disappears"

Oct 11 '25 06:10 hboutemy

Just an idea - change the comment decimeter? Instead of hash use something different or skip comments functionality? Similar was with two dash - as separator for header properties

Oct 19 '25 18:10 slachiewicz