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;
}
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="https://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="2021-02-28"/>
<meta name="generator" content="DocRaptor.com"/>
</head>
Flexbox
Yes, we do support CSS flexbox layouts!
Advanced Topics
Things can get pretty involved with styling PDFs. We've written about some of these more advanced topics in our knowledge base:
- JavaScript
- Styling
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>
<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:

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">02/28/21</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
Set the name
attribute on a table element to name the sheet produced by the 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.
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.
Sets the format for the cell content. If you use a number format on a text or date cell, the results may be unpredictable.
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.
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.
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.
Amount of indentation of the cell content. Integer value from 0 to 14.
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.
Sets the text orientation for this cell. Arbitrary values are not allowed.
Sets the background pattern.
If background-color
is set, solid
is the default.
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.
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.
Sets the border style (lines that appear around a cell). If border-*-color
is set, thin
is the default.
Sets the height of a row, in points. Only valid on <tr>
elements.
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).
Sets if this cell is locked. Only has meaning if a password has been set for the sheet that will contain this cell.
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.
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.
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>