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.
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.
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 is a subset of the W3C CSS specifications:
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.
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).
The weasydoc
package is still in development. You can install the development version from GitHub with:
devtools::install_github('RLesur/weasydoc')
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
.
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.
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/
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/
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
.
There are a lot of great ressources on the web to learn CSS for Paged Media:
O'Reilly Media tutorials on Youtube:
I also recommend this article Streamlining CSS Print Design with Sass by Sanders Kleinfeld (@sandersk) and the Paged Media initiative blog www.pagedmedia.org.
This package is still in active development. Some breaking changes may appear. Feel free to send a PR.
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!