Creating Beautiful PDFs via HTML/CSS/JS

The xkcd cartoon

Why you should learn CSS (Cascading Style Sheets) & JS (JavaScript)

A quick demo to show how you can unlock the $9.99/mo pro plan on Meetup.com for free: https://www.meetup.com/neb-rug/events/306923229/
With CSS, you can change the style of anything you see on any web page
With JS, you can manipulate anything on any web page with code (e.g., the number of your followers, the scores on your school transcript, and the balance in your bank account)

Why not LaTeX or Word?

[…] {xdvir} is built on LaTeX, with all of the joy and pain that that brings.

—Paul Murrell, The {xdvir} Package

See the number of ways that LaTeX users get stuck: https://github.com/yihui/yihui.org/discussions/1089
Word has the notion of “stylesheets” but it’s far less powerful than CSS (e.g., CSS selectors)

The R Markdown ecosystem

classDiagram
  direction BT
  class htmlwidgets {
    +JS apps
    R-dep (26)
    web-dep (*.js/.css)
  }
  class rmarkdown {
    +HTML/LaTeX
    +RTF/Word/PowerPoint/EPub/...
    R-dep (knitr, evaluate, ... 25)
    sys-dep (Pandoc)
    web-dep (Bootstrap/jQuery/...)
  }
  class blogdown {
    +Websites
    R-dep (33)
    sys-dep (Hugo)
  }
  blogdown --|> bookdown
  class pagedown {
    +Paged HTML
    R-dep (38)
    web-dep (paged.js)
  }
  pagedown --|> bookdown
  class distill {
    +Grid layout
    R-dep (48)
    web-dep (distill)
  }
  distill --|> bookdown
  class pkgdown {
    +Package sites
    R-dep (52)
    web-dep (Bootstrap...)
  }
  pkgdown --|> rmarkdown
  class xaringan {
    +HTML slides
    R-dep (32)
    web-dep (remark.js)
  }
  xaringan --|> rmarkdown
  class tufte {
    +Two-column layout
    R-dep (26)
    web-dep (tufte.css)
  }
  tufte --|> rmarkdown
  class bookdown {
    +Books
    R-dep (26)
    web-dep (GitBook...)
  }
  bookdown --|> rmarkdown
  classDef default fill:none
  style rmarkdown fill:lightskyblue

One package to implement them all (not quite)

classDiagram
  class litedown {
    +HTML/LaTeX
    +min [ * ]
    R-dep (xfun, commonmark)
    web-dep (lite.js)
  }
  class rmarkdown {
    +[ * ]
  }
  class pkgdown {
    +[ * ]
  }
  class xaringan {
    +[ * ]
  }
  class tufte {
    +[ * ]
  }
  class blogdown {
    +[ * ]
  }
  class pagedown {
    +[ * ]
  }
  class distill {
    +[ * ]
  }
  class htmlwidgets {
    +[ * ]
  }
  class bookdown {
    +[ * ]
  }
  litedown *-- rmarkdown
  litedown *-- bookdown
  litedown *-- pkgdown
  litedown *-- xaringan
  litedown *-- tufte
  litedown *-- htmlwidgets
  litedown *-- blogdown
  litedown *-- pagedown
  litedown *-- distill
  rmarkdown <|-- bookdown
  rmarkdown <|-- pkgdown
  rmarkdown <|-- xaringan
  rmarkdown <|-- tufte
  rmarkdown <|-- htmlwidgets
  rmarkdown <|-- blogdown
  rmarkdown <|-- pagedown
  rmarkdown <|-- distill
  classDef default fill:none
  style litedown fill:lightcyan
  style pagedown fill:yellow

Creating PDF from HTML

Tariffs on exporting to PDF

— via @shelina.bsky.social

The problems

You can print any web page to PDF with your browser but have little control over
- page header / footer
- table of contents (e.g., page numbers after leading dots)
- footnotes / margin notes
Once you print to PDF, your document is “dead”, e.g., you’ll lose interactivity¹
- Can we have a PDF-like document that preserves nice features of HTML?

The solutions

The CSS paged media module has existed for decades, but web browsers are not interested in implementing it
The JS library paged.js tried to fill the gap (i.e., implement the CSS module via JS), but it’s too complicated in my eyes (33,000+ lines of code)
As a JS amateur, I tried a naive implementation last year, pages.js (400 lines of JS + 200 lines of CSS)
- I have far less expertise than Donald Knuth and Leslie Lamport in typesetting, so please don’t expect too much from my implementation. By “re-invent”, I guess I only achieved 0.01% of what they did, but personally I’m very happy with this 0.01% achievement.
- I’ll use litedown for examples, but pages.js is not tied to litedown

Get started

install.packages('litedown')
litedown::roam()

Create a new document via the + button on the toolbar and then the check box pages.

output: 
  html: 
    meta: 
      css: ["@pages"]
      js: ["@pages"]

Demo

You can download the example Rmd here
Press P or Ctrl + P

Parameters

:root {
  --paper-width: 210mm;
  --paper-height: 297mm;
  --paper-margin-top: 40px;
  --paper-margin-right: 80px;
  --paper-margin-bottom: 40px;
  --paper-margin-left: 80px;
  --page-header-height: 40px;
  --page-header-bottom: 40px;
  --page-footer-height: 40px;
  --page-footer-top: 40px;
}

Style odd/even pages differently

/* increase right margin and decrease left margin for even pages */
.page-even {
  --paper-margin-right: 120px;
  --paper-margin-left: 40px;
}
/* swap left/right margin values for odd pages */
.page-odd {
  --paper-margin-left: 120px;
  --paper-margin-right: 40px;
}
/* show page numbers on the left for even pages */
.page-even .pagesjs-footer {
  &::before {
    content: attr(data-page-number);
  }
  &::after {
    content: " ";
  }
}

Some small features

Page headers and footers are not selectable (so you can copy content continuously)
Bibliography entries are displayed in footnotes (no need to scroll to the end of an article or a book)
The number of pages on one screen depends on the available window width
- You are not limited to the single- or double-page mode (as PDF viewers limit you)

Rebecca purple

In CSS, “rebeccapurple” refers to the color with the hex code #663399, a shade of purple, which was added to the CSS color list in 2014 as a memorial to Rebecca Alison Meyer, the daughter of CSS developer Eric Meyer, who passed away on her sixth birthday.

❀

The litedown documentation

Still incomplete: https://yihui.org/litedown
The pages.js library has not been documented at all
- I wished to use this talk to motivate myself to document it but still didn’t find time
I had two children last year (a real child and a brainchild), and I think you can understand why it’s difficult for me to finish the documentation…

Thank you!

https://github.com/yihui/litedown

Yes, I’m in favor of imposing a tariff on exporting to PDF (from HTML). ↩