prawn

Fast, Nimble PDF Writer for Ruby

4,646

687

4,646

View on GitHub

Top Related Projects

asciidoctor-pdf

1,140

:page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby.

iText for Java represents the next level of SDKs for developers that want to take advantage of the benefits PDF can bring. Equipped with a better document engine, high and low-level programming capabilities and the ability to create, edit and enhance PDF documents, iText can be a boon to nearly every workflow.

python-pdfkit

1,971

Wkhtmltopdf python wrapper to convert html to pdf

Quick Overview

Prawn is a pure-Ruby PDF generation library that provides a set of tools for creating, manipulating, and rendering PDF documents. It is designed to be fast, flexible, and easy to use, making it a popular choice for developers who need to generate PDF files programmatically.

Pros

Flexibility: Prawn allows developers to create complex PDF documents with a wide range of features, including text, images, tables, and vector graphics.
Performance: Prawn is designed to be fast and efficient, with a focus on performance and scalability.
Cross-platform: Prawn is a pure-Ruby library, which means it can be used on a variety of platforms, including Windows, macOS, and Linux.
Active Development: Prawn is an actively maintained project with a large and engaged community of contributors.

Cons

Learning Curve: While Prawn is relatively easy to use, it does have a learning curve, especially for developers who are new to PDF generation.
Limited Functionality: Prawn is primarily focused on PDF generation and may not provide all the features that some users may require, such as advanced PDF editing or manipulation.
Dependency on Ruby: Prawn is a Ruby-based library, which means that it may not be the best choice for developers who are working in other programming languages.
Potential Performance Issues: While Prawn is designed to be fast, large or complex PDF documents may still experience performance issues, especially on older or less powerful hardware.

Code Examples

Here are a few examples of how to use Prawn to generate PDF documents:

# Create a new PDF document
pdf = Prawn::Document.new

# Add text to the document
pdf.text "Hello, World!"

# Add an image to the document
pdf.image "path/to/image.jpg"

# Create a table
data = [["Name", "Age"], ["John", 30], ["Jane", 25]]
pdf.table data

# Draw a rectangle
pdf.fill_color "ff0000"
pdf.rectangle [100, 100], 50, 50
pdf.fill

# Draw a line
pdf.stroke_color "0000ff"
pdf.line [0, 0], [100, 100]
pdf.stroke

# Add a page break
pdf.start_new_page

# Add a page number
pdf.number_pages "Page <page> of <total>", at: [pdf.bounds.right - 50, 0],
                                           style: :italic

Getting Started

To get started with Prawn, you'll need to have Ruby installed on your system. You can then install the Prawn gem using the following command:

gem install prawn

Once you have the gem installed, you can create a new Prawn document and start adding content to it. Here's a simple example:

require 'prawn'

pdf = Prawn::Document.new
pdf.text "Hello, World!"
pdf.save_as "hello.pdf"

This code creates a new Prawn document, adds the text "Hello, World!" to it, and then saves the document as a PDF file named "hello.pdf".

You can find more detailed documentation and examples on the Prawn project's GitHub page: https://github.com/prawnpdf/prawn

Competitor Comparisons

asciidoctor-pdf

1,140

:page_with_curl: Asciidoctor PDF: A native PDF converter for AsciiDoc based on Asciidoctor and Prawn, written entirely in Ruby.

Pros of asciidoctor/asciidoctor-pdf

Supports a wide range of input formats, including AsciiDoc, Markdown, and HTML
Provides a rich set of features for customizing the output, such as themes, fonts, and page layouts
Integrates well with other Asciidoctor tools and the broader Asciidoctor ecosystem

Cons of asciidoctor/asciidoctor-pdf

May have a steeper learning curve compared to Prawn, especially for users unfamiliar with AsciiDoc
Dependency on the Asciidoctor ecosystem, which may not be suitable for all use cases
Potentially slower performance compared to Prawn, especially for large documents

Code Comparison

Prawn:

pdf = Prawn::Document.new
pdf.text "Hello, World!"
pdf.save_as "hello.pdf"

asciidoctor/asciidoctor-pdf:

require "asciidoctor"
require "asciidoctor-pdf"

doc = Asciidoctor.load_file("document.adoc")
Asciidoctor::PDF.convert(doc, to_file: "document.pdf")

pandoc

33,890

Universal markup converter

Pros of Pandoc

Pandoc is a versatile document conversion tool that can handle a wide range of input and output formats, including Markdown, HTML, LaTeX, and more.
Pandoc has a large and active community, with extensive documentation and a wide range of user-contributed extensions and templates.
Pandoc is highly customizable, allowing users to create their own custom filters and templates to suit their specific needs.

Cons of Pandoc

Pandoc can be more complex to set up and configure than Prawn, especially for users who are not familiar with the command-line interface.
Pandoc may have a steeper learning curve than Prawn, particularly for users who are not familiar with the various input and output formats it supports.

Code Comparison

Prawn (Ruby):

pdf = Prawn::Document.new
pdf.text "Hello, World!"
pdf.render_file "hello.pdf"

Pandoc (Haskell):

import Text.Pandoc
main = do
  writeFile "hello.pdf" =<< writeDefaultPdf =<< readMarkdown def "# Hello, World!"

laravel-dompdf

6,718

A DOMPDF Wrapper for Laravel

Pros of barryvdh/laravel-dompdf

Ease of Integration: barryvdh/laravel-dompdf is a Laravel-specific package, making it seamless to integrate with Laravel-based projects.
Simplicity: The package provides a straightforward API for generating PDFs, reducing the complexity of working with the underlying DomPDF library.
Compatibility: The package is actively maintained and compatible with the latest versions of Laravel, ensuring a smooth integration experience.

Cons of barryvdh/laravel-dompdf

Limited Customization: Compared to Prawn, barryvdh/laravel-dompdf may offer less flexibility in terms of customizing the PDF layout and content.
Performance: Prawn is known for its efficient performance, while the performance of barryvdh/laravel-dompdf may be slightly lower due to the additional abstraction layer.
Dependency on DomPDF: barryvdh/laravel-dompdf relies on the DomPDF library, which may have its own limitations and quirks compared to the native PDF generation capabilities of Prawn.

Code Comparison

Prawn:

pdf = Prawn::Document.new
pdf.text "Hello, World!"
pdf.save_as "hello.pdf"

barryvdh/laravel-dompdf:

use Barryvdh\DomPDF\Facade as PDF;

PDF::loadView('pdf.hello')->save('hello.pdf');

dompdf

10,495

HTML to PDF converter for PHP

Pros of dompdf/dompdf

dompdf is a HTML to PDF converter, which can be useful for generating PDF documents from web content.
dompdf supports a wide range of HTML and CSS features, making it suitable for more complex document layouts.
dompdf is relatively easy to integrate into existing web applications.

Cons of dompdf/dompdf

dompdf can be slower and less efficient than Prawn for generating simple PDF documents.
dompdf may have issues with rendering complex or non-standard HTML and CSS.
dompdf has a larger dependency footprint, which can increase the overall project size.

Code Comparison

Prawn:

pdf = Prawn::Document.new
pdf.text "Hello, World!"
pdf.save_to_file "hello.pdf"

dompdf:

$dompdf = new Dompdf\Dompdf();
$dompdf->loadHtml('<h1>Hello, World!</h1>');
$dompdf->render();
$dompdf->stream();

itext-java

1,968

Pros of itext/itext-java

Mature and widely-used library with a large community and extensive documentation
Supports a wide range of PDF features, including advanced typography, graphics, and security
Provides a Java API that is easy to integrate into existing Java applications

Cons of itext/itext-java

Proprietary licensing model, which may not be suitable for all projects
Can be more complex to use than some other PDF libraries, especially for simple use cases
May have a steeper learning curve compared to more lightweight alternatives

Code Comparison

Prawn

pdf = Prawn::Document.new
pdf.text "Hello, World!"
pdf.save_as "hello.pdf"

iText

PdfWriter writer = new PdfWriter("hello.pdf");
PdfDocument pdf = new PdfDocument(writer);
Document document = new Document(pdf);
document.add(new Paragraph("Hello, World!"));
document.close();

python-pdfkit

1,971

Wkhtmltopdf python wrapper to convert html to pdf

Pros of python-pdfkit

Simplicity: python-pdfkit provides a simple and straightforward API for converting HTML to PDF, making it easy to integrate into Python projects.
Dependency Management: python-pdfkit relies on the wkhtmltopdf library, which handles the actual PDF conversion, reducing the need for complex dependency management.
Cross-Platform Compatibility: python-pdfkit can be used on Windows, macOS, and Linux, making it a versatile choice for various development environments.

Cons of python-pdfkit

Limited Customization: Compared to Prawn, python-pdfkit may have fewer options for customizing the PDF output, such as advanced layout and styling capabilities.
Reliance on External Library: The performance and reliability of python-pdfkit are dependent on the wkhtmltopdf library, which may introduce potential issues or limitations.
Lack of Native PDF Generation: python-pdfkit generates PDFs by converting HTML, while Prawn provides a more direct approach to PDF creation using a Ruby-based DSL.

Code Comparison

Prawn (Ruby):

pdf = Prawn::Document.new
pdf.text "Hello, World!"
pdf.save_as "example.pdf"

python-pdfkit (Python):

import pdfkit
pdfkit.from_string('Hello, World!', 'example.pdf')

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot

README

Prawn: Fast, Nimble PDF Generation For Ruby

Prawn is a pure Ruby PDF generation library that provides a lot of great functionality while trying to remain simple and reasonably performant. Here are some of the important features we provide:

Vector drawing support, including lines, polygons, curves, ellipses, etc.
Extensive text rendering support, including flowing text and limited inline formatting options.
Support for both PDF builtin fonts as well as embedded TrueType fonts
A variety of low level tools for basic layout needs, including a simple grid system
PNG and JPG image embedding, with flexible scaling options
Security features including encryption and password protection
Tools for rendering repeatable content (i.e headers, footers, and page numbers)
Comprehensive internationalization features, including full support for UTF-8 based fonts, right-to-left text rendering, fallback font support, and extension points for customizable text wrapping.
Support for PDF outlines for document navigation
Low level PDF features, allowing users to create custom extensions by dropping down all the way to the PDF object tree layer. (Mostly useful to those with knowledge of the PDF specification)
Lots of other stuff!

Should You Use Prawn?

If you are looking for a highly flexible PDF document generation system, Prawn might be the tool for you. It is not a reporting tool or a publishing toolchain, though it could be fairly easily used to build those things.

One thing Prawn is not, and will never be, is an HTML to PDF generator. For those needs, consider looking into FlyingSaucer via JRuby, or one of the WebKit based tools, like Wicked or PDFKit. We do have basic support for inline styling but it is limited to a very small subset of functionality and is not suitable for rendering rich HTML documents.

Supported Ruby Versions and Implementations

Because Prawn is pure Ruby and all of its runtime dependencies are maintained by us, it should work pretty much anywhere. We officially support all Ruby versions suported by Ruby Core Team and JRuby versions of matching Ruby version. However we will accept patches to fix problems on other Ruby platforms if they aren't too invasive.

Installing Prawn

Prawn is distributed via RubyGems, and can be installed the usual way that you install gems: by simply typing gem install prawn on the command line.

You can also install from git if you'd like, the master branch contains the latest developments. We're trying to keep master branch in working order but you may encounter some rough edges and fresh bugs along with bugfixes. We encourage you to try master branch with your application.

Hello World!

If the following code runs and produces a working PDF file, you've successfully installed Prawn.

require "prawn"

Prawn::Document.generate("hello.pdf") do
  text "Hello World!"
end

Of course, you'll probably want to do more interesting things than that...

Manual

The manual is a series of examples that demonstrate use of the wide range of features Prawn provides. You can get a generated version of the latest released Prawn version on the Prawn website. The examples themselves can be found in the manual directory in this repository.

Please note that while the manual is a great introduction and guide to Prawn it's not exhaustive. Please refer to API docs for more complete information on what Prawn provides and how to use it.

To build the manual, here's what you need to do:

Clone the repository
Run gem install -g
Run rake manual, which will generate manual.pdf in the project root

Release Policies

We're trying to not break things unnecessarily but we don't formally follow Semantic Versioning. The reason is that we release a number of experimental APIs. We don't make any promises on their stability. You can assume the stable portion of the API follows Semantic Versioning.

Also note that bug fixes can change behaviour. We don't consider that to be a breaking change for the purposes of versioning. Please test your applications after updating Prawn.

Be sure to read the release notes in CHANGELOG.md each time we cut a new release, and lock your gems accordingly.

Support

The easiest way to get help with Prawn is to post a message to our Discussions.

Feel free to post any Prawn related question there, our community is very responsive and will be happy to help you figure out how to use Prawn, or help you determine whether it's the right tool for the task you are working on.

Please make your posts as specific as possible, including code samples and output where relevant. Do not post any information that should not be shared publicly, and be sure to reduce your example code as much as possible so that those who are responding to your question can more easily see what the issue might be.

Code of Conduct

Prawn adheres to the Contributor Covenant. Unacceptable behavior can be reported to conduct@prawnpdf.org which is monitored by the core team.

Contributing

If you've found a bug or want to submit a patch, please enter a ticket into our GitHub tracker.

We strongly encourage bug reports to come with failing tests or at least a reduced example that demonstrates the problem. Similarly, patches should include tests, API documentation, and an update to the manual where relevant. Feel free to send a pull request early though, if you just want some feedback or a code review before preparing your code to be merged.

If you are unsure about whether or not you've found a bug, or want to check to see whether we'd be interested in the feature you want to add before you start working on it, feel free to post to our mailing list.

You can run our test suite in a few different ways:

Running rake will run the entire test suite excluding any unresolved issues
Running rspec will run the entire test suite including unresolved issues
Running rspec -t unresolved will run only unresolved issues
Running rspec -t issue:NUMBER will run the tests for a specific issue

These filters make it possible for us to add failing test cases for bugs that are currently being researched or worked on, without breaking the typical full suite run.

Maintenance team

Prawn has always been heavily dependent on community contributions, with dozens of people contributing code over the years. In that sense, the lines have blurred to the point where we no longer have a strong distinction between core developers and contributors.

That said, there are a few folks who have been responsible for cutting releases, merging important pull requests, and making major decisions about the overall direction of the project.

Current maintainers

These are the folks to contact if you have a maintenance-related issue with Prawn:

Alexander Mankuta (PointlessOne)

Inactive maintainers

These folks have helped out in a maintenance role in the past, but are no longer actively involved in the project:

Gregory Brown (practicingruby)
Brad Ediger (bradediger)
James Healy (yob)
Daniel Nelson (Bluejade)
Jonathan Greenberg (jonsgreen)
Jamis Buck (jamis)
Evan Sharp (PacketMonkey)

License

Prawn is released under a slightly modified form of the License of Ruby, allowing you to choose between Matz's terms, the GPLv2, or GPLv3. For details, please see the LICENSE, GPLv2, and GPLv3 files.

If you contribute to Prawn, you will retain your own copyright but must agree to license your code under the same terms as the project itself.

History

Prawn was originally developed by Gregory Brown, under the auspices of the Ruby Mendicant Project, a grassroots initiative in which the Ruby community collectively provided funding so that Gregory could take several months off from work to focus on this project.

Over the last several years, we've received code contributions from dozens of people, which is amazing considering the low-level nature of this project. You can find the full list of folks who have at least one patch accepted to Prawn on GitHub Contributors page.

After a long period of inactivity, Prawn reached its 1.0 milestone in 2014 thanks to some modest funding provided to Gregory by Madriska, Inc. (Brad Ediger's company).

Top Related Projects

Convert designs to code with AI

Introducing Visual Copilot: A new AI model to turn Figma designs to high quality code using your components.

Try Visual Copilot