PdfTurtle 🐢 HTML to PDF generation service

A painless html to pdf rendering service

PdfTurtle generates PDF reports and documents from HTML templates or raw HTML.

Try it! Here's a DEMO__🐢__.

🎢 Features

• ✅ Free, OpenSource and Self-Hosted
• 💬 Generate PDFs in a descriptive way from HTML and CSS (with JavaScript support)
• ✨ Supports modern HTML and CSS standards (uses latest Chromium engine)
• 👻 Builtin template engines (go-template, raymond and django)
• 💼 Bundle template and assets in ZIP file (see Bundle workflow)
• 🚀 Fast generation with limited resources (limited multithreading)
• 🔥 Multiple replicas supported (stateless service design)
• 🖥 Frontend (Playground) for rapid development
• 💫 Beautiful fonts included and preoptimized style (CSS) for PDF or print
• 📦 Container image available (see Run with docker)

💥 How to run the service

With docker container (recommended)

The container image is available on Docker Hub.

With the tag *-playground you get a bundled image with the web playground.

docker pull lucasgaitzsch/pdf-turtle

docker run -d \
    -p 8000:8000 \
    --name pdf-turtle \
    --restart unless-stopped \
    lucasgaitzsch/pdf-turtle

Included fonts:

• Open Sans
• Roboto
• Noto Emoji

Config

command line argument	environment variable	type	default	description
--help	-	-	-	Show help
--logDebug	LOG_LEVEL_DEBUG	boolean	false	Debug log level active
--logJsonOutput	LOG_JSON_OUTPUT	boolean	false	Json log output
--renderTimeout	RENDER_TIMEOUT	integer	30	Render timeout in seconds
--workerInstances	WORKER_INSTANCES	integer	30	Count of worker instances
--port	PORT	integer	8000	Server port
--maxBodySize	MAX_BODY_SIZE	integer	32	Max body size in megabyte
--servePlayground	SERVE_PLAYGROUND	boolean	false	Serve playground from path "./static-files/playground/"
--secret	SECRET	string	""	Secret used as bearer token

🚀 How to use

Bundle Workflow (recommended)

flowchart LR
    subgraph PG[PdfTurtle-Playground]
        direction LR
        O(go to<br>pdfturtle.gaitzsch.dev) --> |go to model tab| MO(paste an<br> example model)
        click O href "https://pdfturtle.gaitzsch.dev" "https://pdfturtle.gaitzsch.dev"
        O --> |go to body tab| B(design the body)
        O --> |go to header tab| H(design the header)
        O --> |go to footer tab| F(design the footer)
        O --> |go in asstes menu| A(put your assets)

        OPT(set your<br> options)
        MO --> OPT
        B --> OPT
        H --> OPT
        F --> OPT
        A --> OPT
        OPT --> S(fa:fa-file-zipper save as<br> ZIP bundle)
    end

    subgraph YP[your fancy project]
        direction TB
        PA(provide as asset)
        PA-->CL(use clent lib)
        PA-->SGC(use swagger to<br> build or generate client)
        R(render PDF with<br> bundle and your model)
        CL-->R
        SGC-->R
        R-->BH(fa:fa-smile be happy!)
    end

    S-->|copy zip bundle<br> to your project|YP
    %%PG-->YP

Loading

1. Prepare project

Choose the fitting client lib for your language or generate / build your own by the OpenApi (Swagger) description.

2. Design your PDF in the playground

Go to 🐢PdfTurtle-Playground, put an example model as JSON and design your PDF. Download the bundle as ZIP file and put it in your resources/assets.

3. Call the service with the client and your data

Send a request to a PdfTurtle instance with your bundle and your model. You will get a rendered PDF.

And thats it.

Hint: You can split your bundle

If you want to have the same header for all documents, you can create a ZIP file with with only the header.html and the required assets. Now you can call the Service with multiple bundle files. The service will assemble the files together. Single files can be send as bundle-component without compressing to a ZIP file. All files with other names than "index.html", "header.html", "footer.html" and "options.json" will be put to the folder "/assets/".

PdfTurtle Playground

You can write and test templates with the builtin playground.

Client libs

• 📦 .NET Standard 2.0 (.NET Core 2.0+ & .NET Framework 4.6.1+) Client
• 📦 Golang (Go) Client

Swagger

Use Swagger-UI under /swagger/index.html as API documentation.

You can use the swagger description (/swagger/doc.json or ./server/docs/swagger.json) to generate a API client for the language of your choice.

Postman

You can import the swagger file to test the service with Postman or an alternative.

Included template engines

Template style	Package	PdfTurtle key	URL
Golang	html/template	golang	https://pkg.go.dev/html/template
Django-syntax like (require model. prefix)	pongo2	django	https://github.com/flosch/pongo2
Handlebars-syntax like	raymond	handlebars	https://github.com/aymerick/raymond

Included template functions

Function name	Parameters	Description
marshal	object	Encodes provided object as JSON string
barcodeQr	content	Renders a SVG QR code from content
barcodeEan	content	Renders a SVG EAN code from content
StrContains	haystack, needle	Renders a SVG EAN code from content
strHasPrefix	haystack, needle	Renders a SVG EAN code from content
strHasSuffix	haystack, needle	Renders a SVG EAN code from content
add	float64, float64	Adds two float64 numbers
subtract	float64, float64	Subtracts two float64 numbers
multiply	float64, float64	Multiplies two float64 numbers
divide	float64, float64	Divides two float64 numbers
float64ToInt	float64	Convert a int to float64
intToFloat64	int	Convert a float64 to int
bitwiseAnd	int, int	a & b

Development / Build from source

See README_DEV.md.

🚧 Roadmap

• Bundle/Package support for exchangeable templates
• Client libs
  • .NET Standard 2.0 (.NET Core 2.0+ & .NET Framework 4.6.1+)
  • Golang
  • Kotlin, Java (JVM languages)
  • ..?
• Markdown to PDF
• Preload and cache JavaScript libs

🔨 Contribution

Contributors are welcome! Feel you free to fork the project and open a pull request.

If you wrote a client lib for a uncovered language please contact me. I will create a repo for you or link your client lib in this readme file.

☢ Build with

• go
• chromedp (golang chromium driver)
• goquery
• chromium (render engine)
• raymond (handlebars template engine)
• pongo2 (django template engine)
• zerolog
• go-arg
• barcode and svgo