Repository for pdfgenrs, an application written in Rust used to create PDFs through an API
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 resourcesCheck GitHub releases to find the latest release version
Set up the basic folder structure
mkdir {templates,resources,data,fonts}Create subfolders in templates and data
mkdir {templates,data}/your_appname # your_appname can be anything, but it'll be a necessary part of the API later-
templates/your_appname/should then be populated with your.typTypst 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_appname/should be populated with json files with names corresponding to a target.typtemplate, this can be used to test your PDFs during development of templates. -
fonts/should contain the.ttf,.otf, or.ttcfiles used by your templates. -
For example typ templates see: templates
- https://github.com/navikt/pdfgenrs-test
- https://github.com/navikt/pale-2-pdfgenrs
Base URL (local): http://localhost:8080
<your_appname> maps to a folder under templates/, and <template> maps to a .typ file name in that folder.
Example:
- Template file:
templates/pale-2/pale-2.typ - Endpoint path:
/api/v1/genpdf/pale-2/pale-2
Compiles a Typst template using JSON request data and returns a PDF.
- Request Content-Type:
application/json - Response Content-Type:
application/pdf - Success:
200 OK - Common errors:
404 Not Found(template/app not found)500 Internal Server Error(rendering failed)
curl -s -X POST http://localhost:8080/api/v1/genpdf/<your_appname>/<template> \
-H "Content-Type: application/json" \
-d '{"key":"value"}' \
--output output.pdfConverts HTML in the request body to a PDF.
- Request Content-Type: typically
text/html - Response Content-Type:
application/pdf - Success:
200 OK - Common errors:
500 Internal Server Error
curl -s -X POST http://localhost:8080/api/v1/genpdf/html/<your_appname> \
-H "Content-Type: text/html" \
--data-binary '<html><body><h1>Hello</h1></body></html>' \
--output output.pdfConverts an image to PDF.
- Supported Request Content-Type:
image/pngimage/jpeg
- Response Content-Type:
application/pdf - Success:
200 OK - Common errors:
415 Unsupported Media Type(if not PNG/JPEG)500 Internal Server Error
curl -s -X POST http://localhost:8080/api/v1/genpdf/image/<your_appname> \
-H "Content-Type: image/png" \
--data-binary @image.png \
--output output.pdfCompiles a Typst template using JSON request data and returns HTML.
- Request Content-Type:
application/json - Response Content-Type:
text/html; charset=utf-8 - Success:
200 OK - Common errors:
404 Not Found(template/app not found)500 Internal Server Error(rendering failed)
curl -s -X POST http://localhost:8080/api/v1/genhtml/<your_appname>/<template> \
-H "Content-Type: application/json" \
-d '{"key":"value"}'When DEV_MODE=true, test data from data/{your_appname}/{template}.json is loaded and GET endpoints are enabled:
GET /api/v1/genpdf/{your_appname}/{template}→ returnsapplication/pdfGET /api/v1/genhtml/{your_appname}/{template}→ returnstext/html; charset=utf-8
These endpoints return:
200 OKon success404 Not Foundif template or test data is missing
When DEV_MODE=false, these GET endpoints are not available (405 Method Not Allowed).
200 OKwhen alive500 Internal Server Errorotherwise
200 OKwhen ready500 Internal Server Errorotherwise
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.
Font files are loaded from FONTS_DIR (default: fonts) on startup.
Make sure you have the rust installed using this command:
rustc --versionMake sure you have cargo installed using this command:
cargo --versionFormat the code
cargo fmtRun the linter
cargo clippy --all-targets -- -D warningsBuild the code without running it
cargo buildTo run the tests
cargo testRun the code
cargo runWe 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
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
To get started, please fork the repo and checkout a new branch. You can then build the library
cargo buildSee more info in CONTRIBUTING.md