{"id":19497104,"url":"https://github.com/rlesur/weasydoc","last_synced_at":"2025-04-25T22:31:44.986Z","repository":{"id":78263148,"uuid":"116886674","full_name":"RLesur/weasydoc","owner":"RLesur","description":"Convert R Markdown to PDF Using Weasyprint (or Prince XML)","archived":false,"fork":false,"pushed_at":"2018-09-19T21:39:47.000Z","size":243,"stargazers_count":45,"open_issues_count":7,"forks_count":3,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-08-13T07:14:12.957Z","etag":null,"topics":["pdf-generation","r","rmarkdown","rmarkdown-document","rstats"],"latest_commit_sha":null,"homepage":"","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RLesur.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-10T00:24:08.000Z","updated_at":"2024-07-08T09:44:53.000Z","dependencies_parsed_at":"2023-04-25T04:35:04.090Z","dependency_job_id":null,"html_url":"https://github.com/RLesur/weasydoc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLesur%2Fweasydoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLesur%2Fweasydoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLesur%2Fweasydoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RLesur%2Fweasydoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RLesur","download_url":"https://codeload.github.com/RLesur/weasydoc/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":224019579,"owners_count":17242176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["pdf-generation","r","rmarkdown","rmarkdown-document","rstats"],"created_at":"2024-11-10T21:43:12.346Z","updated_at":"2024-11-10T21:43:13.466Z","avatar_url":"https://github.com/RLesur.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"# weasydoc\n\n[![lifecycle](https://img.shields.io/badge/lifecycle-experimental-orange.svg)](https://www.tidyverse.org/lifecycle/#experimental) [![Travis build status](https://travis-ci.org/RLesur/weasydoc.svg?branch=master)](https://travis-ci.org/RLesur/weasydoc) [![Coverage status](https://codecov.io/gh/RLesur/weasydoc/branch/master/graph/badge.svg)](https://codecov.io/github/RLesur/weasydoc?branch=master) [![CRAN status](https://www.r-pkg.org/badges/version/weasydoc)](https://cran.r-project.org/package=weasydoc)  \n\n_Work In Progress. Do Not Use in Production Yet!_ \n\nThe goal of `weasydoc` is to convert `R Markdown` to `PDF` using [`WeasyPrint`](https://weasyprint.org/) or [`Prince`](https://www.princexml.com/) with **CSS for Paged Media**. \n\n## Motivation\n\nThe usual way to convert `R Markdown` documents to `PDF` relies on `LaTeX`.  \nIn order to customize the rendered document, you have to pass the painful `LaTeX` learning curve.  \n\nSince [`pandoc`](https://pandoc.org/) 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.\n\n### What is CSS for Paged Media?\n\nIn industry, printed document are commonly designed with publishing softwares like [Microsoft Publisher](https://products.office.com/publisher), [Adobe InDesign®](https://www.adobe.com/InDesign) or [Scribus](https://www.scribus.net/).\n\n_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.  \n\n#### The CSS for Paged Media Standard\n\nThe _CSS for Paged Media_ standard is a subset of the [W3C CSS specifications](https://www.w3.org/Style/CSS/specs.en.html):\n\n- [CSS Paged Media Module Level 3](https://www.w3.org/TR/css3-page/)\n- [CSS Generated Content for Paged Media Module](https://www.w3.org/TR/css3-gcpm/)\n- [CSS Page Floats](https://www.w3.org/TR/css-page-floats-3/)\n- [CSS Fragmentation Module Level 3](https://www.w3.org/TR/css-break-3/)\n- ...\n\n#### CSS for Paged Media Converters\n\nSome 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.  \nThe great [print-css.rocks](https://print-css.rocks/) website by Andreas Jung ([@zopyx](https://github.com/zopyx)) offers a [comprehensive list of converters](https://print-css.rocks/tools.html) using _CSS for Paged Media_.\n\n**Note:** a very promising project of the Paged Media initiative named [Paged.js](https://gitlab.pagedmedia.org/tools/pagedjs) proposes a polyfill for Paged Media. I think this could be a game changer.\n\n## Installation\n\n_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)._\n\n### weasydoc installation\n\nThe `weasydoc` package is still in development. You can install the development version from GitHub with:\n\n``` r\ndevtools::install_github('RLesur/weasydoc')\n```\n\n### System requirements\n\n#### Pandoc version\n\nYou need [`pandoc`](https://pandoc.org/) version 2.1.3 or above (but version 2.2.1 or above is recommended).  \nIf you use the [`RStudio` preview release](https://www.rstudio.com/products/rstudio/download/preview/), you do not need to upgrade `pandoc`. Otherwise, [see the installation instruction for `pandoc`](https://pandoc.org/installing.html).\n\n#### HTML to PDF converter\n\nYou need to install a `HTML` to `PDF` converter that supports _CSS for Paged Media_.\n\nFor now, `weasydoc` supports `WeasyPrint` and `Prince`:\n\n- [`WeasyPrint`](https://weasyprint.org/) is an open source software. [See the installation instruction for `WeasyPrint`](https://weasyprint.readthedocs.io/en/latest/install.html) (be careful, WeasyPrint installation is cumbersome on Windows).  \n- [`Prince`](https://www.princexml.com/) 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](https://www.princexml.com/license/)). [See the installation instruction for `Prince`](https://www.princexml.com/doc-install/).\n\n**Ensure that the location of `WeasyPrint` and/or `Prince` is in the `PATH` environment variable.**\n\n## Docker image\n\n[![](https://images.microbadger.com/badges/version/rlesur/weasydoc.svg)](https://microbadger.com/images/rlesur/weasydoc \"Get your own version badge on microbadger.com\") [![](https://images.microbadger.com/badges/image/rlesur/weasydoc.svg)](https://microbadger.com/images/rlesur/weasydoc \"Get your own image badge on microbadger.com\")\n\n**Do not use this image in production.**\n\nIf you are not familiar with the [docker](https://www.docker.com/) images of the [Rocker project](https://www.rocker-project.org/), please read this great tutorial of [rOpenSci](https://ropensci.org/) Labs: https://ropenscilabs.github.io/r-docker-tutorial/\n\nSince the use of `weasydoc` involves tier-softwares installation (`pandoc`, `WeasyPrint`/`Prince`), a docker image built on top of [`rocker/verse:3.5.0`](https://hub.docker.com/r/rocker/verse/) is provided: [`rlesur/weasydoc`](https://hub.docker.com/r/rlesur/weasydoc/). \n\nYou can launch a container using:\n\n```bash\ndocker run --rm -dp 8787:8787 rlesur/weasydoc\n```\n\nBe aware that using this image, you agree with the terms of the Prince end user license: https://www.princexml.com/license/\n\n## MyBinder environment\n\nThe quickest way to test `weasydoc` is to click on the following badge:\n\n[![Binder](https://mybinder.org/badge.svg)](https://mybinder.org/v2/gh/RLesur/weasydoc-demo/master?urlpath=rstudio)  \n\nUsing this environment, you agree with the terms of the Prince end user license: https://www.princexml.com/license/\n\n## Usage\n\nHere is a simple example:\n\n```r\nfile.copy(system.file(\"rmarkdown/templates/hpdf_document/skeleton/skeleton.Rmd\", \n                      package = \"weasydoc\"), \n          \"myfile.Rmd\")\nrmarkdown::render(\"myfile.Rmd\", weasydoc::hpdf_document())\n```\n\nThis package also supports `bookdown` output format. You can use \n`weasydoc::hpdf_book()` to generate a PDF using `bookdown`.\n\n## How can I learn CSS for Paged Media?\n\nThere are a lot of great ressources on the web to learn _CSS for Paged Media_:\n\n- [A Guide To The State Of Print Stylesheets In 2018](https://www.smashingmagazine.com/2018/05/print-stylesheets-in-2018/) by Rachel Andrew\n- [Print CSS Rocks: https://print-css.rocks/](https://print-css.rocks/) by Andreas Jung ([@zopyx](https://github.com/zopyx))\n- [Introduction to CSS for Paged Media](http://www.xmlprague.cz/wp-content/uploads/www.xmlprague.cz/2018/02/CSS-Print.pdf) by Tony Graham ([@tgraham-antenna](https://github.com/tgraham-antenna)), Antenna House - XML Prague 2018 Conference.\n- [Prince User Guide](https://www.princexml.com/doc-prince/)\n\n**O'Reilly Media tutorials on Youtube:**\n\n- [Part 1: Introduction to HTML and CSS](https://www.youtube.com/watch?v=OZeoiotzPFg)\n- [Part 2: Basic Layout and Text Formatting](https://www.youtube.com/watch?v=yyqvXhu-HOc)\n- [Part 3: Paged Media Basics](https://www.youtube.com/watch?v=P-bDFt2wZDA)\n- [Part 4: Generated Content - Counters \u0026 Strings](https://www.youtube.com/watch?v=mTgxZmOpJls)\n\nI also recommend this article [Streamlining CSS Print Design with Sass](https://medium.com/@sandersk/streamlining-css-print-design-with-sass-debaa2a204c3) by Sanders Kleinfeld ([@sandersk](https://github.com/sandersk)) and the **Paged Media initiative** blog [www.pagedmedia.org](https://www.pagedmedia.org/).\n\n## Contribution\n\nThis package is still in active development. Some breaking changes may appear. Feel free to send a PR. \n\n## Credits\n\nThe name `weasydoc` is a tribute to the [WeasyPrint](https://github.com/Kozea/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_.\n\nThanks Christophe Dervieux ([@cderv](https://github.com/cderv)) for making me discover [MyBinder](https://mybinder.org/)! \n\nThe most important source of inspiration comes from the [rmarkdown](https://github.com/rstudio/rmarkdown) and [bookdown](https://github.com/rstudio/bookdown) packages created by Yihui Xie ([@yihui](https://github.com/yihui)). Many thanks!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frlesur%2Fweasydoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frlesur%2Fweasydoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frlesur%2Fweasydoc/lists"}