With the fenced divs notation, sections are inserted exactly when I do not say section!

[kindaro]

My goal is to render a certain paragraph with a header as a section. However, the section tag is not created.

Note that I cannot use the option --section-divs because some of my headers need to stay without sections. With the option --section-divs, Pandoc will create too many sections!

see for yourself

Put this:

::: fancy
## I am a fancy header.
I am some fancy writing.
:::

::: section
## I am a header of a section.
I am a section of writing.
:::

## I am a header without any sections attached.

::: section
Some stylish text without a header.
:::

— Into https://pandoc.org/try/, or run pandoc --from markdown --to html5 on it. This is what you will receive:

<section id="i-am-a-fancy-header." class="fancy">
<h2>I am a fancy header.</h2>
<p>I am some fancy writing.</p>
</section>

<h2 id="i-am-a-header-of-a-section.">I am a header of a section.</h2>
<p>I am a section of writing.</p>

<h2 id="i-am-a-header-without-any-sections-attached.">I am a header
without any sections attached.</h2>

<section>
<p>Some stylish text without a header.</p>
</section>

(I added white space to the output for clarity.)

expected

If I specify class section, Pandoc should create a section. If I do not specify class section, Pandoc should not create a section, but a mere div. (As it does for the paragraph without a header.) Overall, if I write a fenced div in markdown, Pandoc should create some container tag in HTML.

actual

• A section is created when a paragraph without a header is fenced with class section.
• A section is created when a paragraph with a header is fenced with any class that is not special, for example fancy.
• A section is not created when a paragraph with a header is fenced with class section!

discussion

Note that markdown is parsed correctly, as I verified by selecting the output «native». Div blocks are created exactly when a fenced div is specified in markdown. The problem is with the rendering of HTML (either 4 or 5).

[jgm]

This is indeed confusing behavior. I can explain why it happens, but I agree it would be better to behave differently.

Here's why it happens. In the HTML writer, we use the makeSections function to add section divs to the document in every case (even if --section-divs is not specified), because we need this for heading numbering, TOCs, and slide divisions in slide show formats. Then, if --section-divs is not specified, we ignore this section-div structure in rendering the HTML. This causes problems if you've added your own section divs.

Workaround #1: use another class before section, since pandoc recognizes its self-added section superstructure by matching on section as first class:

::: {.foo .section}
# Heading

ok
:::

Workaround #2: put a block element, like an empty HMTL comment, between the start of the section div and the heading:

::: section
<!-- -->
# Heading

ok
:::

Workaround #3: use raw HTML:

<section>
# Header

ok
</section>

[kindaro]

Thank you John!

Maybe we can make the «automatic» sections created by makeSection have a different class, say pandoc-automatic-section, instead of section? Then the «automatic» sections identified by the class pandoc-automatic-section can be ignored while still accounting for «manual» sections identified by the class section. In other words, this will ensure that Pandoc can recognize its self-added superstructure independently of the inherent structure of the document.

I go with workaround № 3 for now, it works fine, so I do not require an immediate fix. I only wanted to share this idea so that I can free my mind of it.

Unfortunately, I cannot find time to work on this issue myself. Maybe at a later time…