u/nikl_me

In the past two years, I developed Oicana, a toolset to use Typst for document templating from your own code. I got frustrated with existing solutions for templating in software and wanted to use Typst for it. But at the time, options to integrate with Typst from software were mostly limited to one language. I needed something that could render the same template in the browser and from C# - so I built it.

Oicana consists of multiple core crates that wrap the Typst compiler crate and define a common template format including snapshot testing and input handling with fallbacks.

An Oicana template consists of "normal" Typst files that can use any packages and a manifest file. This is what a minimal template can look like:

#import "@preview/oicana:0.1.1": setup

#let read-project-file(path) = read(path, encoding: none)
#let (input, oicana-image, oicana-config) = setup(read-project-file)

#set document(date: datetime.today())

= Hello from Typst, #input.info.name

Now we can pass names into the template from any Oicana integration.

[package]
name = "example"
version = "0.1.0"
entrypoint = "main.typ"

[tool.oicana]
manifest_version = 1

[[tool.oicana.inputs]]
type = "json"
key = "info"

To compile the template from your own code, pack it using the Oicana CLI, then use one of the available integrations:

• Browser
• Node.js
• C#
• Java
• PHP
• Python
• Rust

For example, this is the relevant code to render the document from above in Python:

import json
from pathlib import Path

from oicana import CompilationMode, Template

template_bytes = Path("example.zip").read_bytes()

with Template(template_bytes) as template:
    pdf = template.compile(
        json_inputs={"info": json.dumps({"name": "Alice"})},
        mode=CompilationMode.PRODUCTION,
    )

Oicana is source available on GitHub and you can follow the getting started guide to quickly try it out. Usage is free for personal projects, research, education, and open source under the non-commercial license.