Creating a Nice-Looking PDF with pandoc
If you’re familiar with pandoc, you know how useful and flexible it is. One of the many formats that you can convert to using pandoc is PDF.
Before version 2 of the tool, you needed the TeX typesetting system (and the LaTeX extensions) installed on your computer to go directly to PDF. TeX is great, but it’s also quite big. And if you’re only producing the occasional PDF, then it’s overkill to have even a basic TeX system installed on your computer.
With version 2 of pandoc came a new option: –pdf-engine. That option lets you specify which tool to use when doing a conversion to PDF. While you can still use LaTeX (and a few other tools) to do the deed, you don’t need to bother with all that bulk.
Let’s take a look at how to create a PDF from a Markdown file using pandoc and a couple of lighter-weight utilities.
Getting Started
You’ll need pandoc installed on your computer, along with one of these tools:
For our purposes, WeasyPrint and wkhtmltopdf are essentially the same, but there are a couple or three little differences. I’ll touch on one of those differences in a moment.
Doing the Conversion
As I mentioned a few paragraphs ago, I’m going to look at how to create a PDF from a file formatted with Markdown. To do that, open a terminal window on your computer. Navigate to the folder containing the file that you want to convert to PDF and then type either:
pandoc [file-name].md --pdf-engine=weasyprint -o [file-name].pdf
or
pandoc [file-name].md --pdf-engine=wkhtmltopdf -o [file-name].pdf
Where [file-name].md is the name of the Markdown file that you want to convert.
Note: Some people add the -t html option to those commands to create an HTML file that WeasyPrint and wkhtmltopdf then convert to PDF. The command also works without that option.
Here’s the result of a conversion using wkhtmltopdf:
What you get looks pretty much the same when you use WeasyPrint to do the conversion. The result is functional, but it’s not the nice PDF file that I promised you in the title of this article. So let’s look at how to add a bit of visual flair to a PDF generated with pandoc.
Enter Print CSS
Cascading Style Sheets (CSS for short) is a way to change the look and feel of a web page or website. Print CSS extends that to formatting a web page or website to be printed. It adds support for changing page sizes, adding page breaks, hiding elements that shouldn’t be printed, adding a cover page, and more.
I’m not going to into print CSS in any detail here, because it’s a big topic that my little brain has trouble wrapping itself around. However, I’m not going to leave you hanging. Here are some sources of information that can help you get started with print CSS:
- Introduction to PrintCSS and CSS Paged Media
- How to Create Printer-friendly Pages with CSS
- CSS: The Perfect Print Stylesheet
Using Print CSS in a Conversion
Let’s say you’ve crafted your own print CSS file or begged/borrowed one from somewhere. To use it, you’ll need to add the –css= option to the string of options that you use with pandoc.
So, once again, open a terminal window on your computer. Navigate to the folder containing the file that you want to convert to PDF and then type either:
pandoc [file-name].md --pdf-engine=weasyprint --css=pdf-styles.css -o [file-name].pdf
or
pandoc [file-name].md --pdf-engine=wkhtmltopdf --css=pdf-styles.css -V papersize:a5 -o [file-name].pdf
Change pdf-styles.css to the name of your print CSS file. Here’s an example the output, via WeasyPrint, from a print CSS file that I use:
My stylesheet, while fairly basic:
- Sets the size of the page to A5.
- Adds page breaks before every Heading 1.
- Creates margins of 1 inch (2.5 cm) all around.
- Uses the Overpass font for all text.
The first point in the list above is one area in which WeasyPrint and wkhtmltopdf differ. wkhtmltopdf ignores page sizes that you specify in the CSS file. Instead, you need to specify the page size in the conversion command using the option -V papersize:a5.
The examples I’ve included in this article are fairly basic. But, I hope, they’ll help spark a few ideas for converting your documents formatted with Markdown (or another markup language) to PDF using pandoc.