Markdown to HTML – DIVs and ToC issue (ToC omitted)

[PlainMartin]

I am sorry if the following is expected behaviour or has been discussed before, I couldn’t find anything on it in the manual or here.

Converting this to HTML:

# Heading 1

# Heading 2

…creates a level 1 table of contents, as expected. This:

::: {.foo}

# Heading 1

# Heading 2
:::

…creates no ToC at all.

::: {.foo}
# Heading 1

# Heading 2
:::

# Heading 3

… creates a ToC with only Heading 3. And this:

# Heading 1

::: {.foo}

# Heading 2

:::

# Heading 3

…creates a document with a full table of contents, but it moves the Heading 2 ID to the generated DIV (which messes with a JavaScript-based navigation feature in my current projects) – this particular edge case was discussed earlier.

So – is there a way to use ::: DIVs with Pandoc 3.7 that won’t affect ToC generation as described here, with a full table of contents created no matter where DIVs are applied?

Thank you.

[rnwst]

I am able to reproduce this (running pandoc input.md --toc --standalone) and don't see a reason why this shouldn't work. You may have discovered a bug. As a temporary workaround, you could use a Lua filter to construct the TOC yourself.

[PlainMartin]

OK. I’ll admit I only checked the Q&A section, not the bug tracker.

In your Jan 3, 2014 comment, you say:

The real issue is the 'hierarchicalize' function from Text.Pandoc.Shared, which creates a nested section structure based on the outer-level headers of the document. It only looks at outer-level headers and does not recurse into other block-level structures (divs, lists, blockquotes, etc.).

Now I understand the approach and respect the decision not to change it, but let me just ask: From a HTML perspective, a DIV doesn’t really define a new hierarchy / semantic context. From the MDN page:

“The <div> HTML element is the generic container for flow content. It has no effect on the content or layout until styled in some way using CSS […] As a ‘pure’ container, the <div> element does not inherently represent anything. Instead, it’s used to group content so it can be easily styled using the class or id attributes.”

So while I understand that e.g. a <section> or <article> defines a new context that would justify omitting them from a ToC or other indexes, I don’t see why headings in a <div> (that might just be used for layout/styling) are removed from the document hierarchy.

Again – just asking.

And the reason why I stumbled into this is that I really just wanted to apply a background color and some other styling to a section with headings of a longer HTML page, but it shouldn’t be removed from the ToC. Is there another way to achieve this?

Thank you.

[rnwst]

I would argue that a Div does have a semantic meaning, however that meaning can be voided by applying the role="presentation" or role="none" attributes. In these cases, I think pandoc should render contained headers as part of the ToC. I'm also not sure if a containing element having semantics should preclude the header from being included in the ToC. It seemed unexpected to me (and others it seems).

@PlainMartin -- for now you can run pandoc without the native_divs extension (pandoc -f markdown-native_divs), that should fix it.

[PlainMartin]

I tried multiple variations of (HTML and Pandoc) DIVs, with and without native_divs, to no avail.

Later, I had a long and insightful chat with Google Gemini about this topic. Google’s very own HAL seems to know a lot about Pandoc (and appreciate its architecture 😉), and we went through half a dozen options.

In the end, the friendly neighbourhood LLM convinced me that (1) I should “see the light” and accept Pandoc’s approach to hierarchies and DIVs as it is instead of trying to work around it; (2) use --section-divs; (3) apply whatever CSS classes I want to the headings, which will (4) then be transferred to the generated sections. This will require some CSS refactoring, but as a bonus, I’ll not only get full TOCs all the time, but also a solid, section-based structure instead of DIVs sprinkled over my documents wherever I need a different background colour.

(Other suggested options included LUA filters to “lift” headings from DIVs, but this looks like overkill/potentially messy.)

[rnwst]

Using -f markdown-native_divs does work (note that my earlier version of the comment got the syntax wrong), but you have to use raw HTML inside of your Markdown instead of the fenced Divs syntax:

<div class="foo">
# Heading 1

# Heading 2
</div>

Seems like Gemini knows quite a bit about Pandoc! I'm not sure how the Lua filter option is supposed to work though. I think you would have to construct the entire TOC yourself inside of a filter, and then make it available to the template via a metadata variable (that is what I was alluding to in my earlier comment).

[PlainMartin]

Ah; I tried -t html-native_divs…

Confirmed; it does work with raw HTML. Thank you. But by now I really think it’s better to use --section-divs as suggested by John below.

With regard to the Lua code, it was more of a sketch and a few ideas of what to do (“lifting” and then reinserting headers; duplicate them…), and as I’m not a coder, anyway, I didn’t want to go there.

[torstenberg]

You can always use header attributes such as # Heading 1 {.foo} # Heading 2 {.foo} You can expand on this if you need to with this syntax: {#identifier .class .class key=value key=value} Then just make a CCS for the .foo class.

…

Am 04.06.2025 um 09:47 schrieb PlainMartin ***@***.***>: OK. I’ll admit I only checked the Q&A section, not the bug tracker. In your Jan 3, 2014 comment <#997>, you say: The real issue is the 'hierarchicalize' function from Text.Pandoc.Shared, which creates a nested section structure based on the outer-level headers of the document. It only looks at outer-level headers and does not recurse into other block-level structures (divs, lists, blockquotes, etc.). Now I obviously respect that decision, but let me just ask: From a HTML perspective, a DIV doesn’t really define a new hierarchy / semantic context. From the MDN page <https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/div>: “The <div> HTML element is the generic container for flow content. It has no effect on the content or layout until styled in some way using CSS […] As a ‘pure’ container, the <div> element does not inherently represent anything. Instead, it’s used to group content so it can be easily styled using the class or id attributes.” So while I understand that e.g. a <section> or <article> defines a new context that would justify omitting them from a ToC or other indexes, I don’t see why headings in a <div> (that might just be used for layout/styling) are removed from the document hierarchy. Again – just asking. And the reason why I stumbled into this is that I really just wanted to apply a background color and some other styling to a section with headings of a longer HTML page, but it shouldn’t be removed from the ToC. Is there another way to achieve this? Thank you. — Reply to this email directly, view it on GitHub <#10893 (reply in thread)>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ACZ2I7FFAK6UKDG7PBQNXSL3B2P7VAVCNFSM6AAAAAB6PINFZSVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTGMZWGQ2DGNY>. You are receiving this because you are subscribed to this thread.

[PlainMartin]

Yes, I am aware of header_attributes, and I use them extensively. But I would need to style long sections (containing not only headings, but also lists etc.) in a HTML document without these sections disappearing from the ToC.

(I suppose it’s possible to have a simple filter create that kind of “wrapper”, but I wonder if it can be done natively.)

[jgm]

If you use --section-divs, then you'll get a <section> with the specified class and you can use that for styling.