Skip to content

Latest commit

 

History

History
209 lines (154 loc) · 10.6 KB

README.md

File metadata and controls

209 lines (154 loc) · 10.6 KB
Raw

PdfTurtle 🐢 HTML to PDF generation service

build and test Go Report Card codecov Maintainability Rating Reliability Rating Security Rating Lines of Code Docker Pulls

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__🐢__.

Screenshot

🎢 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.

PdfTurtleBundle-Workflow

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

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 Does the haystack contains the needle
strHasPrefix haystack, needle Does the first string starts with the second
strHasSuffix haystack, needle Does the first string end with the second
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

🔨 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