Announcing container-writer: Lua filters for semantic containers in Pandoc, Quarto, LaTeX, ConTeXt and Typst

[plbarrio]

I've released a set of Lua filters designed to improve the handling of semantic containers in Markdown across multiple output formats.

Repository: https://github.com/plbarrio/container-writer

What they do

container-writer.lua

Converts Div/Span elements with specific classes into native constructs depending on the output format:

• LaTeX: \begin{name}...\end{name}
• ConTeXt: \startname...\stopname
• Typst: #block [...] <name>
• HTML/EPUB: classes preserved (CSS-based)

container-strip.lua

Removes selected containers entirely — useful for editorial notes or draft-only content.

container-unwrap.lua

Removes container elements while preserving their content.

Key features

• Whitelist-based mapping of classes
• Support for compound classes (e.g., note.title.icon)
• Per-block overrides (env=...)
• Works with both Divs and Spans
• Format-specific environment remapping
• Predictable, minimalistic behavior

Use cases

• Semantic Markdown that becomes native environments in PDF/Typst/ConTeXt
• Draft vs. final workflows (strip editorial notes in production builds)
• Cleaner separation between content and presentation
• Using existing LaTeX packages (e.g. verse) without writing LaTeX in your source

Examples for LaTeX, ConTeXt, Typst and HTML are included in the repository.

Feedback, suggestions, and edge cases are very welcome.

[iandol]

I think extending this to also add named styles for ODT and DOCX (paragraph and character styles) could be a useful addition for some users. I use something similar for alert box support across TeX, Typst and ODT…

[plbarrio]

Good point. I'm studying how to add support for ODT and DOCX paragraph and character styles. The approach differs slightly from LaTeX environments and commands. I had somethindg in mind in ROADMAP.md that i have to rework for a proper assignment to 'div' o 'span'. For alert boxes I have a companion filter that might complement yours: https://github.com/plbarrio/alerts-normalize

[iandol]

Here is mine, the odt / docx support comes from the addClassAndStyle function: https://github.com/iandol/dotpandoc/blob/master/filters/alerts.lua — very simple, just include the custom-style property.

[plbarrio]

Thanks for sharing — yes, that's essentially what it should be like:

elseif FORMAT == 'docx' or FORMAT == 'odt' then
  el.attributes['custom-style'] = environment
  return el
end

The tricky part is that in LaTeX I map Spans to commands and Divs to environments. I still need to figure out how to handle these different format conventions cleanly in the general case.

[iandol]

You don't need to worry I think, pandoc does the heavy lifing to block <p> and inline <span> elements for odt and docx for you:

> pandoc -t opendocument

::: {.env custom-style="env"}

Content

:::

This is an [inline]{.env custom-style="env"} span.

----------------------

<text:p text:style-name="env">Content</text:p>
<text:p text:style-name="Text_20_body">This is an
<text:span text:style-name="env">inline</text:span> span.</text:p>

[plbarrio]

I tested and it works.

What worries me is Poem example. Poem title is a span, to be mapped as a \poemtitle verse package command. But in docx it should be a block. For now I'll handle it by defining poemtitle as a character style in the reference doc, even if it's not semantically perfect.

[denismaier]

Another great thing would be support for JATS XML.

[plbarrio]

I was abroad for a couple of weeks, and I had some trouble with GitHub’s 2FA while traveling, but now I’m getting back to this.

I didn’t know about JATS XML, and it looks interesting, but I’m not confident I could properly validate the quality of the generated output, especially when deciding how generic div and span elements should be translated into JATS structures.

[wlupton]

I have a comment on the decision to use Typst labels, as in Typst: #block [...] <name>.

I think this is related to #9955 and would like to note that I originally used Typst labels to control styling but was given the strong impression by the Typst community that this was not the way to go. See for example this Discord discussion (I could add a summary if it would be of interest and it's painful for people to access it).

[plbarrio]

I was abroad for a couple of weeks and also had some trouble with GitHub 2FA while traveling, but now I’m getting back to this.

My impression is that a more idiomatic Typst approach would be to map semantic classes to predefined macros or block/text properties instead of generating labels for arbitrary Div/Span elements. For example, something like:

#warning[
...
]

instead of:

#block[...]

with the styling defined separately in the Typst template or helper definitions.

That said, I’m still trying to understand what the best mapping strategy would be for generic Pandoc Div and Span elements, especially when arbitrary classes are involved.