Type to search. Arrow keys to move, Enter to open, Esc to close.

All research
Document generationState as of: 2026-10

Safe LaTeX from YAML text

How free text from YAML gets into a LaTeX template without breaking the build, while the template stays readable LaTeX.

Research question: How can arbitrary YAML text go into a LaTeX template so that a special character never breaks compilation?

Project requirement

CV and cover letter text lives in YAML and is compiled to PDF through LaTeX. The content often contains &, %, #, _ and $, which are control characters in LaTeX, and it must not contain raw LaTeX.

Method and validation

  • Jinja2 with LaTeX-friendly delimiters (\VAR{}, \BLOCK{}, \#{}) plus trim_blocks and lstrip_blocks.
  • Escaping in Jinja2's finalize hook, so it runs on every variable output; autoescape stays off because it is built for HTML.
  • A marker type (Raw) for text that is already safe LaTeX, and a separate URL filter.
  • pytest without LaTeX: special characters, backslash and braces, bold markers, unbalanced markers, missing values, the URL filter and blank lines from block tags. The full build compiles eight PDFs in two languages and two variants.

Findings

  • The default {{ }} delimiters clash with LaTeX braces; custom delimiters keep the template readable as LaTeX.
  • Escaping in finalize cannot be forgotten for a single variable, which makes it safer than a per-variable filter.
  • A single marker type is enough to prevent double escaping.
  • URLs inside \href need only % and # escaped; full escaping breaks the link.
  • Without trim_blocks and lstrip_blocks, block lines leave empty lines, which LaTeX reads as paragraph breaks.
  • An unquoted comma in a YAML flow mapping silently creates an extra key; validating language pairs turns this into a build error.

Decision

Escape in finalize, with Raw as the explicit exception and a dedicated URL filter. The content allows only one markup, **bold**, which the build turns into \textbf{}.

Limits and open questions

  • Checked for the character set used with pdfLaTeX; Unicode edge cases such as math symbols are not tested.
  • No inline markup beyond bold, for example no links or lists inside running text.

Sources