Renderer adapters
Use a renderer adapter when an external program should turn one marked Markdown request into a diagram, formula, download, or other result. Each request names one configured profile. The profile fixes the program, inputs, output form, timeout, and cache identity; Heine checks the request and publishes the result it returns.
This guide assumes that you already have a working Heine site. For complete Typst SVG and KaTeX HTML walkthroughs, including installation, stylesheets, accessibility, and verification, read the reproducible renderer examples. That guide is the maintained source for those external-tool recipes.
Requests, profiles, and trust
Choose an inline request for a short one-line input:
:render[profile]`body` . Choose a block request for a larger input. It
normally begins with :::render[profile] and ends with :::. When its body
contains a literal ::: line, use a longer opening fence and an otherwise
empty closing fence of the same length or longer. Each request selects one
profile from the root heine.toml. Block requests must be ordinary top-level
Markdown blocks. Heine rejects a request in a list item or block quote, or a
paragraph continuation, until it defines how that structure should contain the
replacement. Inline and block requests require an unsegmented Markdown source.
A profile's protocol controls how Heine supplies the checked input. A
stream profile receives one input on standard input and writes one result to
standard output. A workspace profile receives staged files in a temporary
directory and writes its declared primary result file there. inputs lists the
forms a profile accepts: an authored body, a named file, or a named source
bundle. result declares what the renderer returns, such as embedded
HTML, SVG, or MathML, an image, a link, or a light and dark picture. Only an
SVG profile uses materializations to choose whether it embeds SVG or
publishes it as a resource.
External renderers are a trust boundary. A permitted program and any wrapper script run with the operating-system authority of the account that starts Heine. A workspace restricts the files that Heine supplies and receives; it is not a sandbox against a malicious executable. Embedded HTML, SVG, and MathML also have the browser-output authority of trusted project templates. Review the program, every fixed argument, and every declared file or bundle input before you grant permission.
The configured timeout limits the wait for the direct child. For stream profiles, Heine writes the input before starting that wait; a program that stops reading can block the build. A descendant that keeps an output pipe open can also delay completion after the direct child exits. Heine does not manage descendant processes, so renderer wrappers must manage their own children.
Every build that selects a renderer request needs explicit permission:
heine --allow-external-renderersWithout that flag, Heine stops at the request before reading a cache entry or starting a process:
external renderer permission is required here
help: rerun with --allow-external-renderers after reviewing the selected renderer profileHeine does not discover or install a renderer. Check the program yourself
before building, for example with katex --version, typst --version, or
java -version. The profile's cache_identity is your declared version or
environment identity. Change it after changing a renderer or a meaningful part
of its environment.
Heine identifies a failed renderer request at its authored location. When the program exits unsuccessfully, Heine also presents any captured standard error separately. It retains up to 8 KiB, marks truncation, and replaces invalid UTF-8 with replacement characters. Other failures, such as a timeout or an input-write error, report the failure without attaching the captured standard error. For a workspace request with a body, paths and line numbers in that output refer to the isolated staged input.
An embedded SVG request may add a normalized class list to its checked root
element. This lets site CSS style the SVG without a wrapper. HTML and MathML
results remain renderer-owned fragments, so they do not accept class.
PlantUML SVG image
Install Java and download a PlantUML JAR. Replace /absolute/path/plantuml.jar
with the absolute path to that JAR. The profile produces an SVG resource, so
the Markdown request must provide alternative text:
[renderers.plantuml]
protocol = "stream"
program = "java"
timeout_seconds = 20
cache_identity = "plantuml-1.2026.10"
inputs = ["body", "file"]
result = "svg"
materializations = ["resource"]
[renderers.plantuml.block]
arguments = ["-jar", "/absolute/path/plantuml.jar", "--svg", "-pipe"]:::render[plantuml alt="Browser request and application response"]
@startuml
Browser -> Application: request
Application --> Browser: response
@enduml
:::Heine verifies that the returned document has an SVG root element, publishes
the original bytes as heine-renderers/sha256-<digest>.svg, and replaces the
request with an img element. The URL includes the configured site.base_path.
To use a checked page-owned file instead of an inline diagram, declare it in
the adjacent .page file:
[render.architecture]
file = "diagrams/architecture.puml"Then select it from a block request with an empty body:
:::render[plantuml source="architecture" alt="Application architecture"]
:::The declared file is renderer input, not a copied asset.
Typst PDF download
Install the typst command-line program. A workspace profile receives an
isolated input, output, and work directory. Heine names the selected primary
output result.pdf from the configured result extension, so Typst can infer
the format from its destination filename:
[renderers.typst-report]
protocol = "workspace"
program = "typst"
timeout_seconds = 30
cache_identity = "typst-0.15.1"
inputs = ["body", "file", "bundle"]
input_extension = "typ"
result = "link"
media_type = "application/pdf"
extension = "pdf"
[renderers.typst-report.block]
arguments = ["compile", "{input_file}", "{output_file}"]Heine keeps one reusable workspace slot for each workspace profile during a build session. It clears that slot before and after each request. If a platform lock prevents cleanup, Heine keeps a successful result but reports the retained path; later requests retry cleanup instead of allocating unbounded temporary directories.
:::render[typst-report label="Download the one-page report (PDF)"]
= Report title
This PDF was generated while building the site.
:::Heine replaces the request with an a element whose visible text is the
required label. The PDF receives a digest-addressed URL below
heine-renderers/, so changed bytes receive a new public URL.
For a multi-file Typst project, declare a checked source bundle in the page:
[render.report]
root = "reports/quarterly"
entry = "main.typ"The profile can use {input_dir} instead of {input_file} when its fixed
arguments need the staged bundle directory. Heine copies only the declared
bundle files, hashes every checked file into the cache key, and rejects an
extra renderer output file.
Light and dark generated images
result = "picture" represents one meaningful image in fixed light and dark
forms. The profile owns both renderer invocations; a Markdown request supplies
one alternative text and optional picture presentation fields. Heine checks
both resources, emits a native picture, and uses the light source as its
fallback. Read the generated-picture design for
the complete contract.
For complete local Typst SVG and KaTeX HTML walkthroughs, including installation, profiles, stylesheets, accessibility, and test commands, see reproducible renderer examples.
Build and development behavior
The first permitted build runs each selected renderer. Later builds reuse a
typed cache entry when the profile, request form, and complete checked input
are unchanged. Use this command when deliberately checking the installed
tools or after an external change not represented by cache_identity:
heine --allow-external-renderers --refresh-renderersAt the start of each build session, Heine removes incomplete cache files from
an interrupted atomic write. It does not scan the complete cache for every
request, and it does not evict valid entries automatically. Remove .heine/
when you want to discard the private cache completely.
heine serve --allow-external-renderers applies the same permission to every
complete watched rebuild. Renderer source files and bundles live below
content/, so changes trigger a rebuild. A --quick build can update a
selected request after a present body or declared input changes, but it remains
incomplete: change profiles, request structure, source declarations, names, or
paths with a full build.
When identical renderer bytes produce the same digest-addressed resource, Heine publishes that resource once. If another producer claims its path, Heine's collision report identifies every Markdown request that contributed to the shared resource.
A separate resource may select a licensing record
through its profile or its render request. When licensing.required = true,
Heine requires that record before it starts the external program. Ordinary
builds do not run draft-page requests, so a draft resource receives that check
only in a draft preview.
Read the reference for every field and the renderer-adapter design for the trust and output-ownership boundaries.