Reference

The functions and types Twyla adds to Typst’s standard library.

document

document(
  output: autostrfunction,
  title: contentnone,
  date: datetimenone,
  description: contentnone,
  kind: strauto,
  extra: any,
  draft: bool,
  body: content,
) -> content

Defines a page of the website.

Conventionally, document metadata is provided near the top of each page. with a set rule. Every field is then available on this page via #context
document.<field>, and the whole site’s metadata is available through documents().

#set document(
  title: "Rewriting My Blog",
  date: datetime(year: 2026, month: 4, day: 12),
  description: "Why I moved off Markdown.",
  kind: "post",
)

It is also possible to create new pages inline, by constructing documents:

#context link(
    document(
        title: "Page within a page",
        output: auto,
    )[Hello from a page within a page!].url(),
)[This is a link to a page within a page]

.url()

document.url() -> str

The page’s public URL. Two call forms:

• document.url() (no self) → the current page’s URL, built from the output twyla derived for it.
• document(output: "x")[..].url() (method, on an instance) → that document’s URL, and discovers it for emission — so an inline document consumed only through .url() (never shown) is still routed. Discovery dedups by output, so calling .url() repeatedly, or .url() on a document that is also shown, emits it exactly once.

Contextual — call it inside #context. context precedes the optional this self-positional: the #[func] macro classifies special params by name and forwards them ahead of ordinary positionals (the instance is prepended as that positional on a method call).

documents

documents() -> array

The list of every page in the site.

Returns an array with one dictionary per page, each carrying that page’s url plus the metadata it set via #set document(..): url, title, date, description, kind, draft, and extra. Access fields with ordinary dot syntax, e.g. doc.title.

This is contextual — call it inside a #context block:

#context for doc in documents() {
  if doc.kind == "post" and not doc.draft [
    == #link(doc.url, doc.title)
    #doc.date.display()

    #doc.description
  ]
}

asset

.url()

asset.*.url() -> str

The resolved, fingerprinted URL of this asset.

.read()

asset.*.read(
  encoding: "utf8"none,
) -> strbytes

This asset’s bytes, to inline instead of link. Returns a UTF-8 str by default, raw bytes with encoding: none, same as read.

asset.file

asset.file(
  path: pathstr,
  output: autostrfunction,
) -> content

Pulls in a file verbatim as an asset.

#context html.elem("img", attrs: (src: asset.file("logo.svg").url()))

asset.sass

asset.sass(
  path: pathstrbytes,
  format: auto"sass""scss",
  minify: bool,
  output: autostrfunction,
) -> content

Compile a Sass/SCSS file to a fingerprinted CSS asset.

minify is a settable field, so #set asset.sass(minify: false) switches a whole page (or site) to expanded output.

#context html.elem("link", attrs: (
  rel: "stylesheet",
  href: asset.sass("main.scss").url(),
))

asset.svg

asset.svg(
  path: pathstrbytes,
  minify: bool,
  id: noneautostr,
  output: autostrfunction,
) -> content

Minify an SVG asset and optionally set an id on its root element.

#context {
  let icon = asset.svg("icon.svg", id: auto)
  raw-html("<use href=\"" + icon.url() + "#" + icon.elem-id() + "\"/>")
}

asset.image

asset.image(
  path: pathstrbytes,
  width: intnone,
  height: intnone,
  fit: "contain""cover""stretch",
  filter: "nearest""triangle""catmull-rom""gaussian""lanczos",
  format: auto"png""jpeg""gif""webp""avif",
  quality: int,
  output: autostrfunction,
) -> content

Pulls in an image file as an asset.

#context html.elem("img", attrs: (
  src: asset.image("photo.jpg", width: 600, format: "webp").url(),
))

By default, the image file is copied verbatim (same as file). If format is provided, the image will be transcoded. If width/height are provided, the image will be resized.

All parameters are settable, so #set asset.image(format: "webp") applies to any image asset in the scope.

asset.raw

asset.raw(
  data: strbytes,
  extension: str,
  output: autostrfunction,
) -> content

Emit inline data verbatim as an asset.

Use [asset.file](super::file::FileAsset) for a path that should be read and watched; asset.raw never touches the filesystem.

asset.typst

asset.typst(
  source: pathstrcontent,
  format: "svg""png""pdf""html",
  ppi: int,
  minify: bool,
  output: autostrfunction,
) -> content

Compile a typst document (content or a project .typ file) to a fingerprinted asset.

format (default svg) and ppi are settable, so #set asset.typst(format: "pdf") configures a whole scope.

#context html.elem("a", attrs: (
  href: asset.typst("/resume/cv.typ", format: "pdf").url(),
))[Download my CV]

raw-html

raw-html(
  html: strbytes,
) -> content

Splice a string of raw HTML into the output verbatim.

Typst has no first-class raw-HTML node, so for now this wraps the markup in <script type="…">…</script> — a raw-text element typst won’t escape — and twyla’s post-render pass ([crate::render::resolve_raw_html_placeholders]) strips the wrapper back out. Exposing it as a builtin rather than a typst #let keeps call sites stable if we later swap the implementation (e.g. parse the HTML with html5ever and emit real typst nodes).

plain-text

plain-text(
  content: content,
) -> str

The plain text of some content — the same flattening typst uses to derive the document <title> from document(title: …). Useful for slugs, alt text, and other places that need a string from rich content.

sys.twyla-version

sys.twyla-version: version = version(0, 1, 0)

The version of Twyla currently compiling the document, as a version value. The field can be used to detect if Twyla is being used:

#if "twyla-version" in dictionary(sys) [ Hello from Twyla ] else [ Hello from Typst ]