DocRaptor

Documentation

How to Style your Documents

Styling your documents in DocRaptor is as simple (or as complicated) as styling with HTML and CSS. Our PDF engine even supports CSS3, HTML5, SVG, @font-face, and JavaScript. This means, just like a webpage, you can use CSS rounded corners, Google Web Fonts, JavaScript charts, and more in your PDFs.

A few tips to make your life easier:

  • Use the Try It Out page

    You can easily test your markup and styles with our document pipeline on the Try It Out page.

  • Use full URLs for Assets

    Images or other assets not loading? Try using absolute paths or full URLs.

  • Use internal CSS and JavaScript

    While we fully support external stylesheets and JavaScript, using in-document code can reduce your document generation time, as it means fewer requests back to your server.

  • Enable JavaScript for your PDF?

    JavaScript is disabled by default (to speed up document generation), but if you want charts, custom fonts or any other JavaScript based functionality, you will need to enable JavaScript on your API call.

  • We can help!

    Problems styling your document? You can request help for that specific document. We're happy to help debug any problems!

Basic document styling is done with the same HTML and CSS you already know, but some PDF specific and Excel specific functionality requires CSS rules and HTML attributes you might not be used to.

PDF Documents

Size & Orientation

This is probably obvious, but it's worth saying: PDFs have fixed-size pages, but web pages don't. So how do we reconcile that? 1 of 2 ways: either we create page breaks automatically based on the normal flow of your content, or you define where pages should start and stop.

If you want your PDF to be a specific size and aspect ratio, use the special @page selector. You can pass it keywords or specific measurements. All supported keywords can be found here.

Combine your size keyword with a portrait or landscape keyword to define the page's orientation.

// set to standard A4 size
@page { size: A4 }
@page { size: A4 landscape }
// set to custom size
@page { size: 22cm 24cm }
@page { size: 12in 14in }

Margins & Bleed

You can set the following attributes within the @page selector: margin, border, padding and background. A margin of 0 will generate a full-bleed page.

// set to standard A4 size
@page {
  size: A4;
  margin: 0; // full-bleed
  padding: 2in;
  background: #cccccc;
}

linking in generated PDFs is simpler than you might think! There are 2 types of links:

External Links

These of course link to external webpages. They work exactly as in HTML:

<a href="http://docraptor.com/">DocRaptor!</a>

Internal Links

This is how you link to other parts of your document. It's as simple as reference the id of the element you'd like to link to in the URL hash, just as in HTML.

<a href="#section1">Section 1: Getting Started</a>
<div id="section1">First Section</div>

Headers & Footers

You can add headers and footers to PDFs in DocRaptor. Everything you need to know about headers and footer can be found here.

Page Breaks

You can force page breaks or try to avoid them. The following properties allow you to define the behavior: page-break-before, page-break-after, page-break-inside.

These properties can be applied to block-level elements, table rows and table row groups.

You can set them to either always which will always force a page break, or avoid which will avoid breaking if possible.

.chapter { page-break-before: always }
.heading { page-break-after: avoid }

Custom Fonts

Custom fonts are easy to do in DocRaptor. They work just like using fonts on the web, using @font-face selectors. Here's an example of what Google Web Fonts generates for Open Sans:

@font-face {
  font-family: 'Open Sans';
  font-style: normal;
  font-weight: 300;
  src: local('Open Sans Light'), local('OpenSans-Light'), url(http://themes.googleusercontent.com/static/fonts/opensans/v8/DXI1ORHCpsQm3Vp6mXoaTaRDOzjiPcYnFooOUGCOsRk.woff) format('woff');
}
html { font-family: 'Open Sans', sans-serif; }
Font licenses are sticky business, so make sure you have the rights to embed fonts before using them.
Some font-embedding services use JavaScript to load fonts. If so, make sure you enable JavaScript in your document request
We do not yet support WOFF 2.0, please use WOFF 1.0, TTF, or OTF formatted fonts.

PDF Bookmarks

Bookmarks create the outline or table of contents on generated PDFs. They have numeric levels that create a hierarchy (e.g. a bookmark at level 2 can contain nested bookmarks at level 3) The level of a bookmark is set with the prince-bookmark-level property.

h1 { prince-bookmark-level: 1 }
h2 { prince-bookmark-level: 2 }
h3 { prince-bookmark-level: 3 }
h4 { prince-bookmark-level: 4 }
h5 { prince-bookmark-level: 5 }
h6 { prince-bookmark-level: 6 }

To see bookmarks in action, check out our ebook example

PDF Metadata

We extract metadata from the content of HTML metadata elements. The content of the <title> element is used for the document title, and the <meta> element can be used to specify author, subject, keywords, date, and generator application:

<head>
  <title>On 7 Languages</title>
  <meta name="author" content="Jasper Lutz"/>
  <meta name="subject" content="An exploration of 7 programming languages"/>
  <meta name="keywords" content="ruby, python, javascript, go, clojure, haskell, objective-c "/>
  <meta name="date" content="2017-10-18"/>
  <meta name="generator" content="DocRaptor.com"/>
</head>

Flexbox

Unfortunately, we do not yet support CSS flexbox layouts. We hope to in the future, as we also love flexbox layouts, but do not have a timeline for adding support.

Advanced Topics

Things can get pretty involved with styling PDFs. We've written about some of these more advanced topics on our blog:

Excel Documents

To make an Excel file with DocRaptor, your document content should only contain tables. Here is example input of a basic, single worksheet file.

Use CSS to style cells, rows, and the entire table using inline style attributes.

<table name="Example Worksheet">
  <tr style="font-size: 16px">
    <td colspan="2">Big Row</td>
  </tr>
  <tr>
    <td style="color: blue">Blue Cell</td>
    <td style="-xls-format:currency_dollar">1000</td>
  </tr>
</table>
DocRaptor doesn't support writing CSS <style> blocks.

Multiple Worksheets

To make an XLS file with more than one worksheet, just send multiple tables, wrapped in a <tables> tag. With the following input:

<tables>
  <table name="Dino Scale">
    ...
  </table>
  <table name="Dino Budget">
    ...
  </table>
</tables>

This will be your output:

Multiple worksheets

Data Formatting: numbers, currency, dates

You can use the special -xls-format to set the format (number, currency, etc). An example is below, but refer to formatting options below for all the options.

<table>
  <tr>
    <td style="-xls-format:currency_dollar">1000</td>
    <td style="-xls-format:currency_pound">1000</td>
  </tr>
  <tr>
    <td style="-xls-format:float">100.012</td>
    <td style="-xls-format:date_format1">10/18/17</td>
  </tr>
</table>

Merged Cells

To merge cells, set colspan and rowspan attributes on <td> elements:

Special attributes
<table>
  <tr>
    <td colspan="2">Foo</td>
  </tr>
  <tr>
    <td rowspan="2">Bar</td>
    <td>Baz</td>
  </tr>
  <tr>
    <td>foobar</td>
  </tr>
</table>

Worksheet Name & Password

<table name="{VALUE}"></table>

Set the name attribute on a table element to name the sheet produced by the table.

<table password="{VALUE}"></table>

Set the password attribute on a table element to password protect the worksheet produced by the table with the given password. By default this means that all cells in the worksheet will be read-only, unless the password is entered. You can control what cells will be read-only using the -xls-locked style.

Styling Options

DocRaptor supports many CSS style attributes you're already familiar with, plus a few Excel file specific attributes. Here is a complete list of supported attributes.

Content Type & Format

-xls-content-type inline-style only
Options:
  • auto
  • string
  • number
  • formula
  • datetime
  • boolean
  • blank

The content type for the cell in Excel. Auto will try and determine the Excel cell type automatically based off the cell contents. To keep leading zeros, use string. To change the formatting of the content, see -xls-format.

-xls-format inline-style only
Numbers & Text Options:
  • default
  • text
  • integer
  • float
  • percent float
  • percent integer
  • accounting float
  • accounting integer
  • accounting red float
  • accounting red integer
  • exponential
  • fraction_one_digit
  • fraction_two_digits
  • thousands_float
  • thousands_integer
Currency Options:
  • currency_dollar
  • currency_euro_prefix
  • currency_float_euro_prefix
  • currency_euro_suffix
  • currency_japanese_yen
  • currency_pound
Dates & Times Options:
  • date_format1 (m/d/yy)
  • date_format2 (d-mmm-yy)
  • date_format3 (d-mmm)
  • date_format4 (mmm-yy)
  • date_format5 (h:mm AM/PM)
  • date_format6 (h:mm:ss AM/PM)
  • date_format7 (h:mm)
  • date_format8 (h:mm:ss)
  • date_format9 (m/d/yy h:mm)
  • date_format10 (d/m/yy)
  • date_format11 (d/m/yy h:mm:ss) (xlsx-only)
  • date_format12 (dd.MM.yyyy) (xlsx-only)

Sets the format for the cell content. If you use a number format on a text or date cell, the results may be unpredictable.

-xls-thousands-delimiter inline-style only
Options:
  • ,

The character that delimits large numbers (i.e. 1 million written as ‘1,000,000’ is delimited by the comma character). If you are using this, you may want to set ‘-xls-decimal-delimiter’, too.

-xls-decimal-delimiter inline-style only
Options:
  • .

The character that delimits the begin of the decimal portion of numbers (i.e. 11/10 written as 1.1 is delimited by the period character). If you are using this, you may want to set ‘-xls-thousands-delimiter’, too.

Text & Font

color inline-style only
Options:
  • black

Sets the text color for the cell. Can take any named web color or hex value.

Hex values will be translated to the closest of the valid colors for Excel.

font-size inline-style only
Options:
  • 10pt

Sets the font size in points.

font-family inline-style only
Options:
  • Arial

Sets the font family.

font-style inline-style only
Options:
  • normal
  • italic

Sets if the font should be italic or not.

font-weight inline-style only
Options:
  • normal
  • bold
  • bolder
  • lighter
  • 100
  • 200
  • 300
  • 400
  • 500
  • 600
  • 700
  • 800
  • 900

Sets the weight of the font.

text-decoration inline-style only
Options:
  • none
  • line-through
  • underline

Sets the text decoration.

text-align inline-style only
Options:
  • general
  • left
  • right
  • center
  • justify
  • fill

The horizontal alignment for cell content.

vertical-align inline-style only
Options:
  • bottom
  • top
  • center
  • justify

The vertical alignment for cell content.

text-indent inline-style only
Options:
  • 0
  • ...
  • 14

Amount of indentation of the cell content. Integer value from 0 to 14.

white-space inline-style only
Options:
  • nowrap
  • wrap

Cell content wrapping. If set to wrap, then Excel will wrap data in cells with this format so that it fits within the cell boundaries.

-xls-text-orientation inline-style only
Options:
  • horizontal
  • vertical
  • stacked
  • 0
  • 45
  • 90
  • 270
  • 315
  • 360

Sets the text orientation for this cell. Arbitrary values are not allowed.

Background & Border

-xls-background-pattern inline-style only
Options:
  • none
  • solid
  • horizontal stripe
  • vertical stripe
  • reverse diagonal stripe
  • diagonal stripe
  • diagonal crosshatch
  • thick diagonal crosshatch
  • thin horizontal stripe
  • thin vertical stripe
  • thin reverse diagonal stripe
  • thin diagonal stripe
  • thin horizontal crosshatch
  • thin diagonal crosshatch
  • 6.25%
  • 12.5%
  • 25%
  • 50%
  • 75%

Sets the background pattern. If background-color is set, solid is the default.

background-color inline-style only
Options:

Sets the background color for the cell. Can take any named web color or hex value. If -xls-background-pattern is set, grey is the default.

Hex values will be translated to the closest of the valid colors for Excel. Certain colors (such as black) will cause Excel to ignore the background pattern you set.

border-top-color
border-bottom-color
border-left-color
border-right-color inline-style only
Options:

Sets the border color for the cell. Can take any named web color or hex value. If border-*-style is set, black is the default.

Hex values will be translated to the closest of the valid colors for Excel.

border-top-style
border-bottom-style
border-left-style
border-right-style inline-style only
Options:
  • none
  • thin
  • medium
  • dashed
  • dotted
  • thick
  • double
  • hair
  • medium dashed
  • dash dot
  • medium dash dot
  • dash dot dot
  • medium dash dot dot
  • slanted dash dot

Sets the border style (lines that appear around a cell). If border-*-color is set, thin is the default.

Height & Width

height inline-style only
Options:
  • auto

Sets the height of a row, in points. Only valid on <tr> elements.

width inline-style only
Options:
  • auto
  • 1
  • ...
  • 255

Sets the width of a column, in number of characters. The last width specified for a column wins (i.e., if you specify the width for a column in both row 1 and row 2, the width specified in row 2 is used).

Cell Lock

-xls-locked inline-style only
Options:
  • true
  • false

Sets if this cell is locked. Only has meaning if a password has been set for the sheet that will contain this cell.

Row Freezing

-xls-frozen-row inline-style only
Options:
  • true
  • false

Set this style option with a value of true on contiguous tr elements to freeze those rows to the top of the spreadsheet.
Note you must set this option on the first tr in your HTML.

Column Freezing

-xls-frozen-column inline-style only
Options:
  • true
  • false

Set this style option with a value of true on contiguous th and td elements to freeze those rows to the left side of the spreadsheet.
Note you must set this option on the first th or td in your HTML.