pdfgenrs

Repository for pdfgenrs, an application written in Rust used to create PDFs

Technologies & Tools

• Rust
• Cargo
• Axum
• Typst
• Docker

Getting started

Most commonly, pdfgenrs is used as a base image alongside templates, fonts, additional resources, and potential test data to verify that valid PDFs get produced by the aforementioned templates.

In your own repository, create a Dockerfile with the following contents

# Dockerfile
FROM ghcr.io/navikt/pdfgenrs:<release>

COPY templates /app/templates # typst templates
COPY fonts /app/fonts         # fonts to be embedded
COPY resources /app/resources # additional resources

Check GitHub releases to find the latest release version

Set up the basic folder structure

mkdir {templates,fonts,resources,data}

Create subfolders in templates and data

mkdir {templates,data}/your_teamname # your_teamname can be anything, but it'll be a necessary part of the API later

• templates/your_teamname/ should then be populated with your .typ Typst templates. the names of these templates will also decide parts of the API paths. Templates receive JSON data via #let data = json("/data.json").
• data/your_teamname/ should be populated with json files with names corresponding to a target .typ template, this can be used to test your PDFs during development of templates.

Appications that uses pdfgenrs

• https://github.com/navikt/pale-2-pdfgenrs
• https://github.com/navikt/smarbeidsgiver-pdfgenrs

Developing pdfgenrs

Prerequisites

Make sure you have the rust installed using this command:

Rust

rustc --version

Cargo

Make sure you have cargo installed using this command:

cargo --version

Build

Build the code without running it

cargo build

Run

Run the code

cargo run

Running the application with enviroment DEV_MODE = true will exposes a GET endpoint at /api/v1/genpdf/<application>/<template> which looks for test data at data/<application>/<template>.json and outputs a PDF to your browser. The template and data directory structure both follow the <application>/<template> structure.

By default, pdfgenrs will load all assets (templates, data) to memory on startup. Any change on files inside these folders will not be loaded before a restart of the application.

Release

We use default GitHub release. This project uses semantic versioning and does NOT prefix tags or release titles with v i.e. use 1.2.3 instead of v1.2.3

See guide about how to release: creating release github

👥 Contact

This project is currently maintained by the organisation @navikt.

If you need to raise an issue or question about this library, please create an issue here and tag it with the appropriate label.

For contact requests within the @navikt org, you can use the Slack channel #pdfgen

If you need to contact anyone directly, please see CODEOWNERS

✏️ Contributing

To get started, please fork the repo and checkout a new branch. You can then build the library

cargo build

See more info in CONTRIBUTING.md