README.md

In RLesur/weasydoc: Convert R Markdown to PDF Using HTML and CSS

weasydoc

Work In Progress. Do Not Use in Production Yet!

The goal of weasydoc is to convert R Markdown to PDF using WeasyPrint or Prince with CSS for Paged Media.

Motivation

The usual way to convert R Markdown documents to PDF relies on LaTeX. In order to customize the rendered document, you have to pass the painful LaTeX learning curve.

Since pandoc version 2 supports PDF generation through HTML+CSS, formatting PDF document can now be achieved through CSS. For those who already know HTML and CSS, learning CSS for Paged Media is quite easy.

What is CSS for Paged Media?

In industry, printed document are commonly designed with publishing softwares like Microsoft Publisher, Adobe InDesign® or Scribus.

CSS for Paged Media can mainly be understood as an alternative for these publishing softwares: it allows conversion from HTML to PDF using CSS rules.

The CSS for Paged Media Standard

The CSS for Paged Media standard is a subset of the W3C CSS specifications:

• CSS Paged Media Module Level 3
• CSS Generated Content for Paged Media Module
• CSS Page Floats
• CSS Fragmentation Module Level 3
• ...

CSS for Paged Media Converters

Some important features of CSS for Paged Media are not implemented by the top browsers in use. So, you cannot rely on browsers (or headless browsers) to generate a PDF file from HTML using CSS for Paged Media: you have to install a converter that implements the CSS for Paged Media standard. The great print-css.rocks website by Andreas Jung (@zopyx) offers a comprehensive list of converters using CSS for Paged Media.

Note: a very promising project of the Paged Media initiative named Paged.js proposes a polyfill for Paged Media. I think this could be a game changer.

Installation

If you do not want to modify your system, you can use the rlesur/weasydoc docker image or even easier the MyBinder environment (see below).

weasydoc installation

The weasydoc package is still in development. You can install the development version from GitHub with:

devtools::install_github('RLesur/weasydoc')

System requirements

Pandoc version

You need pandoc version 2.1.3 or above (but version 2.2.1 or above is recommended). If you use the RStudio preview release, you do not need to upgrade pandoc. Otherwise, see the installation instruction for pandoc.

HTML to PDF converter

You need to install a HTML to PDF converter that supports CSS for Paged Media.

For now, weasydoc supports WeasyPrint and Prince:

• WeasyPrint is an open source software. See the installation instruction for WeasyPrint (be careful, WeasyPrint installation is cumbersome on Windows).
• Prince is a commercial software. However, you can use Prince for non-commercial purposes: a notice is included in the PDF and you have to mention the www.princexml.com web address when distributing the PDF files (see the end user licence agreement). See the installation instruction for Prince.

Ensure that the location of WeasyPrint and/or Prince is in the PATH environment variable.

Docker image

Do not use this image in production.

If you are not familiar with the docker images of the Rocker project, please read this great tutorial of rOpenSci Labs: https://ropenscilabs.github.io/r-docker-tutorial/

Since the use of weasydoc involves tier-softwares installation (pandoc, WeasyPrint/Prince), a docker image built on top of rocker/verse:3.5.0 is provided: rlesur/weasydoc.

You can launch a container using:

docker run --rm -dp 8787:8787 rlesur/weasydoc

Be aware that using this image, you agree with the terms of the Prince end user license: https://www.princexml.com/license/

MyBinder environment

The quickest way to test weasydoc is to click on the following badge:

Using this environment, you agree with the terms of the Prince end user license: https://www.princexml.com/license/

Usage

Here is a simple example:

file.copy(system.file("rmarkdown/templates/hpdf_document/skeleton/skeleton.Rmd", 
                      package = "weasydoc"), 
          "myfile.Rmd")
rmarkdown::render("myfile.Rmd", weasydoc::hpdf_document())

This package also supports bookdown output format. You can use weasydoc::hpdf_book() to generate a PDF using bookdown.

How can I learn CSS for Paged Media?

There are a lot of great ressources on the web to learn CSS for Paged Media:

• A Guide To The State Of Print Stylesheets In 2018 by Rachel Andrew
• Print CSS Rocks: https://print-css.rocks/ by Andreas Jung (@zopyx)
• Introduction to CSS for Paged Media by Tony Graham (@tgraham-antenna), Antenna House - XML Prague 2018 Conference.
• Prince User Guide

O'Reilly Media tutorials on Youtube:

• Part 1: Introduction to HTML and CSS
• Part 2: Basic Layout and Text Formatting
• Part 3: Paged Media Basics
• Part 4: Generated Content - Counters & Strings

I also recommend this article Streamlining CSS Print Design with Sass by Sanders Kleinfeld (@sandersk) and the Paged Media initiative blog www.pagedmedia.org.

Contribution

This package is still in active development. Some breaking changes may appear. Feel free to send a PR.

Credits

The name weasydoc is a tribute to the WeasyPrint project: I like open source and really appreciate the effort of the community to develop an open source software using CSS for Paged Media.

Thanks Christophe Dervieux (@cderv) for making me discover MyBinder!

The most important source of inspiration comes from the rmarkdown and bookdown packages created by Yihui Xie (@yihui). Many thanks!

RLesur/weasydoc documentation built on May 21, 2019, 9:19 a.m.