Tools for generating, validating, and outputting XML using Typst syntax.

The page above is examples/create-from-relaxng.typ rendered by Typst: it derives typechecked element constructors from a RELAX NG grammar, then validates and prints a document — pointing right at the mistakes in an invalid one.

Authoring XML

Create functions which return XML elements with make-tag/make-tags. Use the resulting functions using standard typst syntax. Named arguments are converted to attributes and positional arguments are treated as children.

make-tag(tag, handlers: auto) -> function

Creates a tag function for a single element named tag. handlers overrides how body content is converted to XML (see Markup in bodies). The returned tag function takes named arguments as attributes and positional arguments as children: <tag>(..args) -> content.

make-tags(..names, handlers: auto) -> array

Creates one tag function per name, returned in order for destructuring; handlers is forwarded to each.

#import "@preview/xmlit:0.1.3": make-tags, xml-to-string

#{
  let (foo, bar) = make-tags("foo", "bar")

  // Typst native XML parsing
  let xml1 = xml(bytes(`<foo><bar baz="zz" />text</foo>`.text))

  // Construct XML by passing using function arguments
  let xml2 = foo(bar(baz: "zz"), "text")

  // Construct XML by passing using a code block
  let xml3 = foo({
    bar(baz: "zz")
    "text"
  })

  // Construct XML by passing content
  let xml4 = foo[#bar(baz: "zz")text]

  [
    // All versions render as `<foo><bar baz="zz" />text</foo>`
    #xml-to-string(xml1)

    #xml-to-string(xml2)

    #xml-to-string(xml3)

    #xml-to-string(xml4)
  ]
}

Markup in bodies

Inside content ([...] blocks) markup is automatically converted into tags:

• *bold* → <b>bold</b>
• _emph_ → <em>emph</em>
• `code` → <c>code</c>
• $x^2$ → <m>x^2</m>
• $ ... $ → <md>…</md>

This mapping can be overwritten by providing handlers to the make-tag function.

#import "../src/lib.typ": *

#let p = make-tag("p", handlers: (
  // strong -> <alert> instead of <b>
  "strong": (c, convert, ctx) => ((tag: "alert", attrs: (:), children: convert(c.body)),),
  // Control how the _content_ of math is serialized.
  "math": (body, convert, ctx) => ("MATH: \"" + repr(body) + "\"",),
  // Control what tag is used for math blocks.
  "equation": (c, convert, ctx) => {
    let f = c.fields()
    let tag = if f.block { "md" } else { "m" }
    // Use the math handler we defined already.
    let math-handler = ctx.handlers.at("math")
    ((tag: tag, attrs: (:), children: math-handler(f.body, convert, ctx)),)
  },
))

// Becomes: `<p>A <alert>very important</alert> point about <m>MATH: "attach(base: [x], t: [2])"</m>. It can sometimes be solved with <md>MATH: "root(radicand: [⋅])"</md></p>`
#xml-to-string(p[
  A *very important* point about $x^2$. It can sometimes be solved with
  $
    sqrt(dot)
  $
])

A handler has the signature handler(element, convert, ctx)

• convert turns any child value (e.g. the element’s body) into an array of XML nodes using the same handler table
• ctx provides an object that can be used to look up other handlers that are defined. They will be defined on ctx.handlers.

Unmapped markup (e.g. headings) raises an error naming the element and the handlers: entry that would map it.

Preserving Math

There is no way (in typst 0.15) to serialize all math such that eval can evaluate it as valid typst code. Since you may want access to the math (for example, measure it), the extract-math: true option may be passed to xml-to-string. If passed, it returns a dictionary (xml, math-items): all found math is collected into math-items and the math in the XML string is replaced with a sentinel.

#let (xml, math-items) = xml-to-string(doc, extract-math: true)
// xml:        "<p>Area: <m>⟦math-0⟧</m></p>"   (text sentinels, ⟦id⟧)
// math-items: ("math-0": $pi r^2$, ...)         (real equation content)

// rendered sizes, keyed by the same ids that appear in the XML:
#context math-items.pairs().map(((id, eq)) => (id, measure(eq)))

Ids are assigned in document order (“math-0”, “math-1”, …), so they are deterministic across compiles. The default (no extract-math).

See examples/render-xml-with-math.typ for an example where xml is produced with math rendered as “math” via typst.

Typechecked authoring from a RELAX NG grammar

create-from-relaxng(rnc, handlers: auto, wasm: auto) -> dictionary

create-from-relaxng derives tag functions from a RELAX NG grammar (compact syntax, .rnc) and validates the composed document via a bundled WASM plugin (see plugin/). It returns (elements: dictionary, utils: dictionary). Parameters:

• rnc — the grammar source (str/bytes), or a (file-name: contents) dictionary for multi-file grammars (the first entry is the entry point).
• handlers — forwarded to every generated tag function.
• wasm — the validator plugin; defaults to the bundled one.

#import "@preview/xmlit:0.1.3": create-from-relaxng

#let (utils, elements) = create-from-relaxng(
  "start = element foo { element bar { attribute baz { text } }* }",
)
#let (foo, bar) = elements

#show: utils.validate-and-render

#foo[#bar(baz: "xx")]

The returned dictionary destructures into two entries:

• elements — a dictionary mapping each element name defined in the grammar to its tag function (destructure the ones you need, as above).
• utils — grammar-level helpers, each accepting pretty-print: false where applicable (see Pretty printing):

  • render(body, pretty-print: false) -> content — a template (#show: utils.render) that serializes its body and renders the XML source without validating. Useful for fast iteration; switch to validate-and-render once the document is ready to be checked.

  • validate-and-render(body, pretty-print: false) -> content — a template (#show: utils.validate-and-render) that serializes its body, validates it against the grammar, and renders the XML source. Invalid documents fail compilation with a readable panic that includes a small line-numbered snippet of the source around each error, not the whole document:

    XML failed RELAX NG validation:
    - element <qux> is not allowed here. Expected element(s): bar.
        1 | <foo>
      > 2 |   <qux />
              ^^^^^^^
        3 | </foo>
    

    No (line, column) is shown — those would be positions in the invisible, internally-generated compact XML string, not anything actually written.

    The snippet is windowed both by line (a couple of lines of context) and, within the target line itself, by character count — pretty-printing only breaks lines between all-element children, so a <p> full of prose (or even a whole document with no element-only nesting) can pretty-print to one very long line; the character-level window is what keeps the snippet short regardless.

    Use .with(pretty-print: true) in a show rule: #show: utils.validate-and-render.with(pretty-print: true).

  • render-and-show-validation-errors(body, pretty-print: true) -> content — a template (#show: utils.render-and-show-validation-errors) for authoring/preview: like validate-and-render, but instead of panicking on an invalid document it renders the XML source anyway, highlighting each offending element’s line in place with its error message. Errors that can’t be tied to a specific element are listed below the block. Useful while iterating on a document you know isn’t finished yet.

  • validate(doc) -> (valid: bool, errors: array) — validate content or an XML string without panicking. On failure, each entry in errors also carries a snippet — the same windowed source excerpt used in validate-and-render’s panic message (none only for errors with no locatable position, e.g. an internal buffer-limit error). For a raw doc string the snippet windows directly around the error’s position in that string (no round-trip through the grammar needed), and the plugin’s raw line/column fields are kept, since they index the exact string written. For authored content the snippet is mapped through the element that produced it, and line/column are removed — those would be positions in an invisible, internally-generated XML string, not anything actually written, so they’d only mislead.

  • roots — the element names allowed as the document root. (All element names are elements.keys().)

A handlers: argument passed to create-from-relaxng is forwarded to every generated tag function, so one handler table configures markup/math conversion for the whole grammar (see Markup in bodies).

Serializing

xml-to-string(node, handlers: auto, extract-math: false, pretty-print: false) -> str | dictionary

xml-to-string accepts authored trees (the return value of a tag function or any markup content), plain node dictionaries/strings/arrays, and — faithfully — the output of Typst’s built-in xml() reader. Parameters:

• node — an authored tree, a node dict/str/array, or xml() reader output.
• handlers — overrides for content conversion (see Markup in bodies).
• extract-math — return a (xml, math-items) dictionary with equations pulled out (see below).
• pretty-print — indent element-only content (see below).

#xml-to-string(xml("doc.xml"))

Attribute order is preserved, text/attribute contexts are escaped correctly, empty elements self-close, and default-namespace declarations are re-emitted only where the namespace actually changes.

Pretty printing

Pass pretty-print: true to indent the output. Only elements whose children are all elements are reflowed — one child per line; elements containing any text (mixed content) stay inline, so no significant whitespace is introduced:

#xml-to-string(root(a(b()), b(id: "2")), pretty-print: true)
// <root>
//   <a>
//     <b />
//   </a>
//   <b id="2" />
// </root>

#xml-to-string(p[Some *bold* text], pretty-print: true)
// <p>Some <b>bold</b> text</p>   (mixed content — left inline)

Pretty-printed output is meant for reading; it is not byte-faithful to xml() reader input.