pdf-turtle

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

🚀 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

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

Included template functions

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