go-typst

go-typst is a Go library that leverages the command-line interface of Typst to provide functions for the creation of documents and reports in various formats (PDF, SVG, PNG). Its goal is to provide Go developers with a seamless, "Go-like" interface to Typst's powerful document generation capabilities.

Stability and Compatibility

go-typst is a work in progress, and the API may change as Typst evolves. Supported Typst versions are tested by unit tests to ensure compatibility.

Supported Versions:

• Typst 0.12.0
• Typst 0.13.0
• Typst 0.13.1
• Typst 0.14.0

While breaking changes may occur, i aim to minimize disruptions. Use at your own discretion for production systems.

Features

• PDF, SVG and PNG generation.
• All Typst parameters are discoverable and documented in cli-options.go.
• Go-to-Typst Value Encoder: Seamlessly inject any Go values.
• Encode and inject images as a Typst markup simply by wrapping image.Image types or byte slices with raw JPEG or PNG data.
• Errors from Typst CLI are returned as structured Go error objects with detailed information, such as line numbers and file paths.
• Uses stdio; No temporary files will be created.
• Good unit test coverage.

Installation

1. Use go get github.com/Dadido3/go-typst inside of your project to add this module to your project.
2. Install Typst by following the instructions in the Typst repository.

Runtime requirements

This module assumes that the Typst executable is accessible from your system's PATH. Ensure that you have Typst installed on any machine that your project will be executed. You can install it by following the instructions in the Typst repository.

Alternatively you can pack the Typst executable with your application. In this case you have to provide the path to the executable when setting up the typst.CLI object:

typstCLI := typst.CLI{
    ExecutablePath: "./typst", // Relative path to executable.
}

Note

Make sure to follow the Typst license requirements when you pack and distribute the Typst executable with your software.

Usage

Here we will create a simple PDF document by passing a reader with Typst markup into typstCLI.Compile and then let it write the resulting PDF data into a file:

func main() {
    r := bytes.NewBufferString(`#set page(width: 100mm, height: auto, margin: 5mm)
= go-typst

A library to generate documents and reports by utilizing the command line version of Typst.
#footnote[https://typst.app/]

== Features

- Encoder to convert Go objects into Typst objects which then can be injected into Typst documents.
- Parsing of returned errors into Go error objects.
- Uses stdio; No temporary files need to be created.
- Test coverage of most features.`)

    typstCLI := typst.CLI{}

    f, err := os.Create("output.pdf")
    if err != nil {
        t.Fatalf("Failed to create output file: %v.", err)
    }
    defer f.Close()

    if err := typstCLI.Compile(r, f, nil); err != nil {
        t.Fatalf("Failed to compile document: %v.", err)
    }
}

The resulting document will look like this: