typstAsis: Emit Raw Typst Markup Without Requiring `results='asis'`

Description

Marks a character string as raw Typst source so that Quarto/knitr renders it directly -- as real typeset Typst content -- rather than displaying it as literal escaped text. This lets print/render methods that build Typst output (for example typst_describe, typst_describe_single, or the Typst branch of a print.X/latex.X method) return their result normally, with no results='asis' chunk option required anywhere in the calling document.

Usage

typstAsis(x)

Value

If called during a knitr/Quarto render, an object of class

knit_asis (see asis_output), which knitr inserts into the rendered document verbatim. Otherwise, the fenced string is printed to the console via cat and returned invisibly.

Arguments

x: A character string (or vector, coerced via paste0) containing complete, valid Typst markup.

Details

typstAsis wraps x in a Pandoc raw-block fence (````{=typst} ... ````) and, when running inside a knitr/Quarto render, returns the result via asis_output. Returning an asis_output object as the visible top-level value of a chunk is what knitr's own knit_print dispatch recognizes as content to insert verbatim rather than escape -- this is the mechanism, confirmed empirically, that requires no new knit_print method to be registered for any particular class: any function that ultimately returns typstAsis(...) as its result renders correctly, regardless of how deeply the string was built up inside helper functions.

The fence uses four backticks, not the usual three. This is deliberate: if x itself contains a triple-backtick sequence (for example, output from a helper that wraps captured print output in its own raw block, such as typst_verbatim), an ordinary three-backtick outer fence would be closed prematurely by that inner sequence, silently corrupting everything in the document that follows -- confirmed directly as the cause of a real rendering failure during development. Pandoc's fenced-block matching only closes a fence with another fence of at least the same length, so a four-backtick outer fence cannot be broken by an inner three-backtick one.

When not running inside a knitr render (for example, when called interactively at the R console while developing or testing a typst_* function), typstAsis falls back to printing x via cat and returning it invisibly, so typst_* functions remain directly usable outside Quarto documents.

Important: x must already be genuine, complete Typst syntax. typstAsis does not translate or interpret its argument in any way -- it only marks already-finished Typst markup so Pandoc passes it through untouched. This means typstAsis must not be used to wrap LaTeX-syntax math content that is meant to be parsed by Pandoc's own markdown reader and translated to Typst via texmath (for example, the equation content built by latexrms and its calling latex.X methods) -- wrapping such content in a {=typst} raw block prevents Pandoc from ever recognizing it as math to translate, and it will be inserted unchanged, as literal LaTeX syntax, into a Typst document. That kind of content should instead be returned via a bare asis_output call, with no raw-block fence, so Pandoc's markdown/math parsing sees it directly.

Examples

Run this code

if (FALSE) {
# Inside a print/render method's typst branch:
typst_describe <- function(object, ...) {
  R <- c(typstFunctions$spikehist, ...)  # build up Typst content
  typstAsis(paste(R, collapse = '\n\n'))
}

# NOT appropriate: LaTeX-syntax math meant for texmath translation
# should use bare knitr::asis_output(), never typstAsis()
}