litedown: A Minimal Re-implementation of the R Markdown Ecosystem

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

A new minimal implementation

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

Minimalism

Until we have begun to go without them, we fail to realize how unnecessary many things are. We’ve been using them not because we needed them but because we had them.

— Lucius Annaeus Seneca

It is not the man who has too little that is poor, but the one who hankers after more.

— Seneca, “Letters from a Stoic”

The two richest men in Omaha, Nebraska

1. Warren Buffet

2. ???

(if you think from the perspective of “degrees of freedom”…)

The path to richness

An example:¹

knitr (<= v1.41)
  |> evaluate 
  |> highr 
  |> stringr 
    |> cli glue lifecycle magrittr rlang stringi vctrs 
  |> yaml 
  |> xfun 

knitr (> v1.41)
  |> evaluate 
  |> highr 
  |
  |
  |> yaml 
  |> xfun 

A summary of my career 2011-2023

A brief history

• 1984: Donald Knuth, Literate Programming

• 1987: WEB and CWEB

• 1989: noweb

• 2002: Sweave, the pioneer in automated report generation

  • R + LaTeX

  • RIP, Fritz Leisch (1968-2024)!

  • If you are still using Sweave today and feel comfortable with it, you are as rich as a billionaire!

• 2011: knitr (language-agnostic)

  • 2011-10-16: initial development

  • 2012-01-17: initial CRAN release

  • 66 CRAN releases in 13 years

• 2012: the first generation of R Markdown, based on the R package markdown (N.B. not rmarkdown!), and only supports HTML output

• 2014: the second generation of R Markdown, i.e., the rmarkdown package, based on Pandoc for multiple output formats (HTML, Word, PDF, PowerPoint, E-book, etc.)

R Markdown extensions, since 2016

Quarto (2022)

• In theory, you can use dozens of computing languages in R Markdown (not limited to R), but R has to be installed in the first place, no matter if you use R or not in R Markdown

• Generalizing 10+ years of experience from R Markdown (e.g., bookdown) to a wider community (e.g., Python and Julia)

• Quarto supports both knitr and jupyter, so Python users can use the jupyter engine (no need to install R), and R users can continue to use knitr

R Markdown in 2012 vs 2024

The above comparison does not include R Markdown extension packages such as bookdown and blogdown, which are even heavier.

⚡ litedown ⚡ (2024)

Make Markdown HTML Again

Do one thing, and do it well

In HTML I Trust

Do you know how awesome web browsers are?…

(now cast the spell “go up”, “go down”, “dark mode”, “mirror my slides”, “edit my slides”, “hi *anyone…” (voice input), or “reset my slides”)

Minimalism: my new journey

• Github repo: https://github.com/yihui/litedown

$$\mathrm{litedown} = \min{\{R\}} + \{D_i\} - \{D_e\} + \{J\}$$

• \(R\) = knitr + evaluate + rmarkdown + bookdown + blogdown + pagedown + pkgdown + xaringan + tufte + distill + htmlwidgets

• \(D_i\) = (internal dependencies) commonmark + xfun

• \(D_e\) = (external dependencies) Pandoc + Bootstrap + jQuery + GitBook + Hugo + paged.js + remark.js + tufte.css + distill.js/.css + …

• \(J\) = Lightweight vanilla JS/CSS

• Re-implementing 12 years of work from scratch, with fewer features and dependencies²

  • Easier to develop, install, and manage

  • Also easier to be embedded in other applications (e.g., WebAssembly)

• Choosing a stable foundation to develop software on top of

  • e.g., base R, commonmark³

  • Reproducibility would be hard without stability

• Almost “feature-complete” in my eyes after a few months’ work (not because I’m smart but limited scope and a decade’s thinking)

  

• Users will surely request for more features, but litedown is unlikely to gain major new features

Demos

# install from CRAN
install.packages('litedown')
# or install the dev version (recommended for now)
install.packages('litedown', repos = 'https://yihui.r-universe.dev')

• Core functions: litedown::mark() to convert plain Markdown documents; litedown::fuse() to compile R Markdown documents

• The live previewer: litedown::roam()

• Full documentation still under development: https://yihui.org/litedown/

• Figures and tables / Time code chunks / R scripts, books, and slides / JS and CSS assets (you can download the demo Rmd here)

Custom execution order of code

I don’t have enough time showcase all possibilities of litedown, so let me highlight one tiny feature that I came up with when rethinking about literate programming.

---
title: A nice report
abstract: "In this report, we studied `{r} nrow(x)` cars."
---

Filter cars with `mpg` above 20.

```{r, order = 0}
x = subset(mtcars, mpg > 20)
```

Thank you!

https://yihui.org