container-writer.lua / container-strip.lua / container-unwrap.lua

Three companion Pandoc Lua filters:

• container-writer.lua — translates generic Div and Span containers into format-native environments for LaTeX, ConTeXt and Typst, named styles for DOCX/ODT, and passthrough for HTML/EPUB.
• container-strip.lua — removes Div and Span elements by class, content and all, for stripping editorial annotations in production builds.
• container-unwrap.lua — removes Div and Span container elements while preserving their content. Useful as a post-processing step after container-writer.lua to neutralise elements that were not in the whitelist.

Copyright 2026 Pedro Luis Barrio under GPL-3.0-or-later, see LICENSE file for details.

Maintained by plbarrio.

Requirements

Pandoc >= 2.19.1 · Quarto >= 1.4.0 (for Quarto usage)

Usage

Plain Pandoc

pandoc --lua-filter=container-writer.lua input.md -o output.pdf

Quarto

Declare in _quarto.yml:

filters:
  - container-writer.lua

How it works

Pandoc renders Div and Span elements with CSS classes natively in HTML/EPUB. In other formats they are invisible — content is emitted but without any wrapping. This filter bridges that gap by wrapping whitelisted containers in the appropriate format command.

Element	LaTeX	ConTeXt	Typst	DOCX/ODT	HTML/EPUB
Div	\begin{name}...\end{name}	\startname...\stopname	#block[...] <name>	paragraph style name	unchanged
Span	\name{...}	\name{...}	#[...] <name>	character style name	unchanged

DOCX and ODT work differently from the other formats: instead of emitting raw markup, the filter sets Pandoc's custom-style attribute and lets Pandoc do the work. Pandoc maps it to a paragraph style for Div and to a character style for Span — the same block/inline split the filter already uses elsewhere, so no extra configuration is needed.

The effective whitelist for a given format is common + the FORMAT-specific list. Containers not in the whitelist are left untouched.

Both common and format-specific keys accept a scalar for a single entry or a list for multiple entries:

container-writer:
  common: epigraph

container-writer:
  common:
    - epigraph
    - note

Only whitelisted names are processed — unknown containers never cause errors in the output format.

Parent.child entries

Compound entries (parent.child) control how nested elements are wrapped. When a Div or Span with class parent is visited, its children matching class child are wrapped using the child's own class name as environment — mirroring the AST directly:

container-writer:
  common:
    - note
    - note.title    # Div.title inside Div.note → \begin{title}

Entries chain to any depth, one level per dot, and each level is wrapped with its own class name:

container-writer:
  common:
    - note
    - note.title
    - note.title.icon   # Div.icon inside Div.title inside Div.note

A level only wraps if its full chain is whitelisted, so note.title alone leaves a deeper icon untouched.

In HTML/EPUB children are left as-is — rendered natively by Pandoc, styled via CSS descendant selectors (.note .title { ... }). In Typst and ConTeXt the child style can be scoped inside the parent rule. In LaTeX \begin{title} is global — use the remap syntax to give it a per-context name.

Remap entries

A compound entry can remap the child's environment name for specific formats:

container-writer:
  common:
    - note
    - note.title          # HTML/EPUB: uses class name 'title'
  latex:
    - note.title: notetitle   # LaTeX: uses 'notetitle' instead
  context:
    - note.title: notetitle   # ConTeXt: uses 'notetitle' instead

This lets CSS use .note .title naturally while LaTeX/ConTeXt use \begin{notetitle} / \startnotetitle — fully per-context, no global namespace collision.

Remap is also useful to avoid conflicts with existing LaTeX environments. If a class name collides with an environment already defined by your document class or a package, remap it to a different name without changing your source:

container-writer:
  latex:
    - dedication: mydedication   # avoids collision with existing \dedication

Then define mydedication in your preamble instead of dedication.

If the parent is not in the whitelist but parent.child is, the parent passes through unwrapped while its matching children are still processed.

Markdown syntax

::: epigraph
Content of the epigraph block.
:::

A paragraph with [an inline span]{.sidebar} inside.

Per-block override

Use the env or environment attribute to override the environment name for a specific block, provided the name is in the whitelist:

::: {.epigraph env=myepigraph}
Content.
:::

Output examples

LaTeX

\begin{epigraph}
Content of the epigraph block.
\end{epigraph}

A paragraph with \sidebar{an inline span} inside.

ConTeXt

\startepigraph
Content of the epigraph block.
\stopepigraph

A paragraph with \sidebar{an inline span} inside.

Typst

#block[
Content of the epigraph block.
] <epigraph>

A paragraph with #[an inline span] <sidebar> inside.

HTML

<div class="epigraph">
  <p>Content of the epigraph block.</p>
</div>

<p>A paragraph with <span class="sidebar">an inline span</span> inside.</p>

DOCX

The filter sets custom-style; Pandoc turns it into a real Word style:

<w:pStyle w:val="epigraph"/>   <!-- from the Div  — paragraph style -->
<w:rStyle w:val="sidebar"/>    <!-- from the Span — character style -->

ODT

<text:p text:style-name="epigraph">Content of the epigraph block.</text:p>
<text:p text:style-name="Text_20_body">A paragraph with
<text:span text:style-name="sidebar">an inline span</text:span> inside.</text:p>

---

Usage examples

Editorial margin notes

A practical case for review workflows: annotations visible in draft builds, removed entirely in production by container-strip.lua — no changes to source files needed.

[this scene needs more tension]{.marginnoteopen}
[checked against sources]{.marginnoteclosed}

::: marginnoteopenblock
Longer note spanning multiple lines.
:::

Review build:

pandoc --lua-filter=container-writer.lua input.md -o draft.pdf

Production build:

pandoc --lua-filter=container-strip.lua \
       --lua-filter=container-writer.lua \
       input.md -o final.pdf

container-strip:
  - marginnoteopen
  - marginnoteclosed
  - marginnoteopenblock
  - marginnoteclosedblock

Style files: notes.tex, notes.ctx, notes.typ, notes.css.

Using existing LaTeX packages without writing LaTeX

A whitelisted class name that matches an environment defined by a LaTeX package works out of the box — no \newenvironment needed in your preamble, no raw LaTeX in your source files.

markdown

::: verse
Shall I compare thee to a summer's day?\
Thou art more lovely and more temperate.
:::

yaml

container-writer:
  common:
    - verse

latex

\usepackage{verse}

The filter emits \begin{verse}...\end{verse} and the package provides the implementation. Your source stays pure Markdown across all output formats — ConTeXt, Typst and HTML use their own definitions independently.

---

Typst templates

Labels allow #show rules to target the containers:

#show <epigraph>: it => block(
  inset: (left: 2em, right: 2em),
  above: 1em,
  below: 1em,
  text(style: "italic", it)
)

LaTeX setup

Define the environments in your preamble or template:

\usepackage{epigraph}
% or define manually:
\newenvironment{epigraph}{\begin{quote}\itshape}{\end{quote}}

ConTeXt setup

\definestartstop[epigraph]
  [before={\blank\startnarrow},
   after={\stopnarrow\blank}]

DOCX / ODT setup

Styles are not defined in the source — they live in a reference document. Create one, define the styles by name, and pass it when converting:

pandoc --print-default-data-file reference.docx > styles/mydoc.docx

Open it, define a paragraph style named epigraph and a character style named sidebar, save, and then:

pandoc --lua-filter=container-writer.lua \
       --reference-doc=styles/mydoc.docx input.md -o output.docx

In Quarto:

format:
  docx:
    reference-doc: styles/mydoc.docx
  odt:
    reference-doc: styles/mydoc.odt

A whitelisted name with no matching style in the reference document does not break the build. Pandoc creates the definition on the fly, based on the default body style:

<w:style w:type="paragraph" w:customStyle="1" w:styleId="epigraph">
  <w:name w:val="epigraph"/><w:basedOn w:val="BodyText"/><w:qFormat/>
</w:style>

The style then exists in the output and is listed in the word processor, but carries no formatting of its own. Unlike LaTeX, nothing warns you that the definition was missing — the text simply looks unstyled.

container-strip.lua

Removes Div and Span elements by class — content and all. Configure with a separate YAML key. Accepts a scalar for a single class or a list:

container-strip: marginnoteopen

container-strip:
  - marginnoteopen
  - marginnoteclosed
  - marginnoteopenblock
  - marginnoteclosedblock

pandoc --lua-filter=container-strip.lua \
       --lua-filter=container-writer.lua \
       input.md -o output.pdf

Note: container-strip must run before container-writer — if writer runs first it converts spans to raw format commands that strip never sees.

---

container-unwrap.lua

Removes Div and Span container elements while preserving their content. Useful after container-writer.lua to neutralise elements not in the whitelist that would otherwise render differently across Pandoc versions (e.g. #block[] in Typst 3.9 vs nothing in 3.1).

Must run after container-writer.lua — the writer converts whitelisted elements to raw format commands that unwrap never sees.

pandoc --lua-filter=container-writer.lua \
       --lua-filter=container-unwrap.lua \
       input.md -t typst

Accepts a scalar or a list. Two reserved keywords control bulk behaviour:

• all — unwrap every remaining Div/Span regardless of class
• void — unwrap elements that carry no class at all

container-unwrap: all

container-unwrap: void

container-unwrap: sidebar

container-unwrap:
  - void
  - sidebar
  - note

Known limitations

• A container name present in both Div and Span contexts uses the same environment name. If your format requires different names for block and inline, use the env attribute to override per block.

• LineBlock (|) inside a whitelisted Div is not processed by this filter.

• Use letters only in container names — no hyphens, no leading digits. Write marginnoteopen, or a short prefix like mnopen, rather than marginnote-open. CSS classes and Typst labels accept hyphens freely, but the TeX formats do not, and the same name is often used for both a Div and a Span.

  Where it actually breaks, if you are wondering how strict this is:

  	Div	Span
  LaTeX	works — \begin{} resolves the name via \csname	fails: Undefined control sequence
  ConTeXt	fails — the name is glued to \start	fails
  Typst, HTML, DOCX, ODT	fine	fine

  Both TeX engines report the failure rather than producing a wrong document silently, so a hyphen you get away with in LaTeX will still stop the build in ConTeXt. If a name has to keep its hyphen in HTML or Typst, use a remap entry to give it a TeX-safe name per format:

  container-writer:
    latex:
      - marginnote-open: marginnoteopen

  The filter deliberately does not strip hyphens for you. Doing so would replace a loud failure with a quieter one: the document would compile, call an environment nobody defined, and name it in the error message with a spelling that appears nowhere in your source. It would also let note-title and notetitle collapse into a single environment without saying so.

• container-strip does not support compound entries — blacklist entries are plain class names only. To strip Div.title inside Div.note, list title explicitly (strips all .title elements) or list the specific classes you want removed.

• ODT needs a recent Pandoc for Span — custom-style on inline elements is ignored by the ODT writer in Pandoc 3.1.3: the character style is dropped and the text comes out unstyled. Verified working in 3.10. DOCX handles both Div and Span correctly in 3.1.3, and ODT handles Div correctly too — only the ODT/Span combination is affected.

• A Span becomes a character style in DOCX/ODT, never a paragraph style. When a container is semantically a block but written inline — a poem title on its own line, say — the word processor cannot give it spacing or keep with next, because character styles do not carry paragraph properties. Model it as a Div if it needs paragraph-level formatting.

Issues and contributing

Issues and PRs welcome at the project repository.

License

GPL-3.0-or-later. See LICENSE.

References

• Pandoc — universal document converter
• Quarto — open-source scientific publishing system
• Lua — lightweight embeddable scripting language
• Pandoc Lua filters — official documentation
• Quarto extensions — official documentation