Introducing a lightweight version of R Markdown

Yihui Xie @ ASA Philly Webinar Series

2023-05-18

1. The basic idea

Source document -> Markdown output -> Target document

Examples:

We only talk about the second step today, i.e., converting .md.


2. The tradeoff



3. Is this lightweight version of R Markdown for you?

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

Letters from a Stoic (Lucius Annaeus Seneca)

Unless you consider yourself a minimalist or a hacker, you may not benefit much from this talk (please feel free to leave at any time during the talk).

For most people, I think rmarkdown and Quarto are better choices.


4. Advantages of “lightweight”



5. Disadvantages


6. Summary of pros and cons

commonmark markdown rmarkdown
Installation commonmark: 1.1 Mb markdown: 2 Mb rmarkdown: 83 Mb, Pandoc: 152 Mb (or RStudio: 1.7 Gb)
Rendering fastest fast slower
Output file size N/A small (start from ~3 Kb) big (start from ~800 Kb)
Learning easy easy it depends
Features minimal moderate rich

7. Renew the old news


8. Convert Markdown with markdown::mark()

I’m using markdown v1.7 today:

install.packages('markdown')
# packageVersion('markdown') >= '1.7'

The core function is markdown::mark():

cat(markdown::mark('Hello **world**!', format = 'latex'))
#> Hello \textbf{world}!
cat(markdown::mark('Hello **world**!', format = 'html'))
#> <p>Hello <strong>world</strong>!</p>

9. Generate full HTML and LaTeX documents



10. Markdown options

The argument options of markdown::*_format controls Markdown features, e.g., whether to enable TOC (table of contents) or section numbering:

---
output:
  markdown::html_format:
    options:
      toc: true
      number_sections: true
---

The full list of available options: vignette('intro', package = 'markdown')


11. The template

To render a full document, we need a template. For example, this is a simple HTML template:

<html>
  <head>
    <title>$title$</title>
    <style type="text/css">$css$</style>
  </head>
  <body>$body$</body>
</html>

markdown::mark() generates the document body, and the rest of template $variables$ get their values from metadata (see the next slide).


12. Metadata

The argument meta of markdown::*_format contains metadata variables to be passed to the template.

output:
  markdown::html_format:
    meta:
      title: "A different title"
      css: "custom.css"
  markdown::latex_format:
    meta:
      documentclass: "book"
      header_includes: "\\usepackage{microtype}"

13. Lots of possibilities for customization


14. Applications

14.1 HTML slides

---
output:
  markdown::html_format:
    meta:
      css: [default, slides]
      js: [slides]
---

You can learn more in vignette('slides', package = 'markdown').


14.2 HTML article

---
output:
  markdown::html_format:
    meta:
      css: ["default", "@xiee/utils/css/article.min.css"]
      js: ["@xiee/utils/js/sidenotes.min.js,appendix.min.js"]
---

Learn more in vignette('article', package = 'markdown').


15. Feature complete: a software engineer’s dream

I have been thinking about a question in recent years:

Why has it become so rare that a software package can declare being “feature complete”? In other words, why is it so hard to reach “feature complete” now?

Where have the old days of “do one thing and do it well” gone?

Developing software is often like playing an infinite game now, which can become exhausting.

I’m happy to declare that the markdown package is mostly feature complete: it has included all features that I want from Markdown.


Thanks!