Prawn HTML

gem version gem downloads maintainability linters specs

HTML to PDF renderer using Prawn PDF. Nerya's maintained fork with added features.

Features:

  • support a good set of HTML tags and CSS properties;
  • handle document styles;
  • custom data attributes for Prawn PDF features;
  • no extra settings: it just parses an input HTML and outputs to a Prawn PDF document.

Notice: render HTML documents properly is not an easy task, this gem support only some HTML tags and a small set of CSS attributes. If you need more rendering accuracy take a look at other projects like WickedPDF or PDFKit.

prawn-styled-text rewritten from scratch, finally!

Please :star: if you like it.

Install

  • Add to your Gemfile: gem 'prawn-html' (and execute bundle)
  • Just call PrawnHtml.append_html on a Prawn::Document instance (see the examples)

Examples

require 'prawn-html'
pdf = Prawn::Document.new(page_size: 'A4')
PrawnHtml.append_html(pdf, '<h1 style="text-align: center">Just a test</h1>')
pdf.render_file('test.pdf')

To check some examples with the PDF output see examples folder.

Alternative form using PrawnHtml::Instance to preserve the context:

require 'prawn-html'
pdf = Prawn::Document.new(page_size: 'A4')
phtml = PrawnHtml::Instance.new(pdf)
css = <<~CSS
  h1 { color: green }
  i { color: red }
CSS
phtml.append(css: css)
phtml.append(html: '<h1>Some <i>HTML</i> before</h1>')
pdf.text 'Some Prawn text'
phtml.append(html: '<h1>Some <i>HTML</i> after</h1>')
pdf.render_file('test.pdf')

Supported tags & attributes

HTML tags (using MDN definitions):

  • a: the Anchor element
  • b: the Bring Attention To element
  • blockquote: the Block Quotation element
  • br: the Line Break element
  • code: the Inline Code element
  • col: the Col table element
  • colgroup: the Colgroup table element
  • del: the Deleted Text element
  • div: the Content Division element
  • em: the Emphasis element
  • h1 - h6: the HTML Section Heading elements
  • hr: the Thematic Break (Horizontal Rule) element
  • i: the Idiomatic Text element
  • ins: the added text element
  • img: the Image Embed element
  • li: the list item element
  • mark: the Mark Text element
  • ol: the Ordered List element
  • p: the Paragraph element
  • pre: the Preformatted Text element
  • s: the strike-through text element
  • small: the side comment element
  • span: the generic inline element
  • strong: the Strong Importance element
  • sub: the Subscript element
  • sup: the Superscript element
  • table: the Table element
  • tbody: the Table Body element, children of table
  • td: the Table Data element, children of table
  • th: the Table Header element, children of table
  • tr: the Table Row element, children of table
  • u: the Unarticulated Annotation (Underline) element
  • ul: the Unordered List element

CSS attributes (dimensional units are ignored and considered in pixel):

  • background: for mark tag (3/6 hex digits or RGB or color name), ex. style="background: #FECD08"
  • break-after: go to a new page after some elements, ex. style="break-after: auto"
  • break-before: go to a new page before some elements, ex. style="break-before: auto"
  • color: (3/6 hex digits or RGB or color name) ex. style="color: #FB1"
  • font-family: font must be registered, quotes are optional, ex. style="font-family: Courier"
  • font-size: ex. style="font-size: 20px"
  • font-style: values: :italic, ex. style="font-style: italic"
  • font-weight: values: :bold, ex. style="font-weight: bold"
  • height: for img tag, ex. <img src="image.jpg" style="height: 200px"/>
  • href: for a tag, ex. <a href="http://www.google.com/">Google</a>
  • left: see position (absolute)
  • letter-spacing: ex. style="letter-spacing: 1.5"
  • line-height: ex. style="line-height: 10px"
  • list-style-type: for ul, a string, ex. style="list-style-type: '- '"
  • margin-bottom: ex. style="margin-bottom: 10px"
  • margin-left: ex. style="margin-left: 15px"
  • margin-top: ex. style="margin-top: 20px"
  • position: absolute, ex. style="position: absolute; left: 20px; top: 100px"
  • src: for img tag, ex. <img src="image.jpg"/>
  • text-align: left | center | right | justify, ex. style="text-align: center"
  • text-decoration: underline, ex. style="text-decoration: underline"
  • top: see position (absolute)
  • width: for img tag, support also percentage, ex. <img src="image.jpg" style="width: 50%; height: 200px"/>

The above attributes supports the initial value to reset them to their original value.

For colors, the supported formats are:

  • 3 hex digits, ex. color: #FB1;
  • 6 hex digits, ex. color: #abcdef;
  • RGB, ex. color: RGB(64, 0, 128);
  • color name, ex. color: yellow.

Data attributes

Some custom data attributes are used to pass options:

  • dash: for hr tag, accepts an integer or a list of integers), ex. data-data="2, 4, 3"
  • mode: allow to specify the text mode (stroke|fill||fill_stroke), ex. data-mode="stroke"
  • colwidth: for col tag only, accepts a float value, ex. colwidth="100"
  • width: for td tag only, accepts a float value, ex. colwidth="100"
  • colspan: for td tag, accepts an integer value, ex. colspan="2"
  • rowspan: for td tag, accepts an integer value, ex. rowspan="2"

Document styles

You can define document CSS rules inside an head tag. Example:

<!DOCTYPE html>
<html>
<head>
  <title>A test</title>
  <style>
    body { color: #abbccc }
    .green {
      color: #0f0;
      font-family: Courier;
    }
    #test-1 { font-weight: bold }
  </style>
</head>
<body>
  <div class="green">
    Div content
    <span id="test-1">Span content</span>
  </div>
</body>
</html>

Additional notes

Rails: generate PDF on the fly

Sample controller's action to create a PDF from Rails:

class SomeController < ApplicationController
  def sample_action
    respond_to do |format|
      format.pdf do
        pdf = Prawn::Document.new
        PrawnHtml.append_html(pdf, '<h1 style="text-align: center">Just a test</h1>')
        send_data(pdf.render, filename: 'sample.pdf', type: 'application/pdf')
      end
    end
  end
end

More details in this blogpost: generate PDF from HTML

Table support through Prawn::Table

Prawn HTML partially supports tables through Prawn::Table. It is not a full implementation, but it is a good start.

Example:

require 'prawn-html'
pdf = Prawn::Document.new(page_size: 'A4')
PrawnHtml.append_html(pdf, '<table>
  <thead>
    <tr>
      <th><b>Header 1</b></th>
      <th><b>Header 2</b></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>Cell 1</td>
      <td>Cell 2</td>
    </tr>
    <tr>
      <td>Cell 3</td>
      <td>Cell 4</td>
    </tr>
  </tbody>
</table>')
pdf.render_file('test.pdf')

This will generate a PDF with a table with two columns and two rows. The table style is fixed, but it accept inline styles in cells. Warning: it doesn't support inline <p></p> html tags. However, it is possible to use <span></span> tags to style the text.

It will also support html table attributes, like width, colspan and rowspan. If no width value is provided, the table will be auto-sized.

Do you like it? Star it!

If you use this component just star it. A developer is more motivated to improve a project when there is some interest.

Or consider offering me a coffee, it's a small thing but it is greatly appreciated: about me.

Contributors

License

The gem is available as open-source under the terms of the MIT.