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.

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;
}

Links

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; }

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="2018-09-24"/>
  <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 and be formatted as XML, not HTML.

Here is an example of a basic, single worksheet file. CSS is used 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>

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:

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">09/24/18</td>
  </tr>
</table>

Merged Cells

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

<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

Character Escaping

Excel documents must be written in XML, not HTML. XML has strict escaping requirements for text content:

• Ampersands (&) should be &
• Quotation marks (") should be "
• Apostrophes (') should be '
• Less than (<) should be <
• Greater than (>) should be >