Why write in RMarkdown/bookdown?

There needs to be adequate provision for all readers to engage with all digital content. LaTeX-produced PDFs are a lossy format for maths content. For example, the structure/semantics of equations is not accessible for a pdf produced using LaTeX to a visually impaired student.

An alternative workflow to writing documents in LaTeX is to write them in RMarkdown instead (specifically the bookdown package, which handles the organisation and appearance of content). This produces HTML pages with the maths equations rendered using MathJax, which is broadly accessible to many and works well with assistive technologies. The advantages of writing in RMarkdown to authors are:

  • Maths syntax is same as LaTeX - possibility of converting existing notes.
  • Easy and clean syntax to use, in contrast to verbose LaTeX markup.
  • Can use Rmarkdown to generate LaTeX, pdf, html, beamer outputs.
  • Allows you to focus on the content. The RMarkdown documents are plain text files that have content without detailed typesetting commands (document properties are controlled elsewhere in a separate .yaml file).
  • HTML output is easy to navigate and works well on different devices, zoom levels etc.
  • HTML content can be embedded directly into the bookdown page (e.g. a video explanation or geogebra widget).

How do I get started with RMarkdown (bookdown)?

  1. An excellent starting point is the Making Lecture Notes with Bookdown (Scowcroft 2020) guide, which runs through most key steps for authors, particularly those coming from a LaTeX background who are interested in converting their existing LaTeX source. Please note the pandoc converter will only be able to convert .tex to .rmd where possible (e.g. TikZ does not exist inside Rmarkdown so cannot be converted - the outputs would need to be included separately instead).
  2. Authoring Books and Technical Documents with R Markdown (Xie 2020) gives detailed documentation on the bookdown package for authors.
  3. Please also join the bookdown usergroup on Microsoft Teams, where staff can share their experiences, issues and solution with using Rmarkdown and bookdown.
  4. Software setup. This is detailed in the resources above but you will need
    • R or Rstudio (bookdown extension installed)
    • pandoc (for converting between formats)
    • LaTeX (for PDF output)

ClavertonDown for advanced users

ClavertonDown is written by Emma Cliffe (MASH) and builds on bookdown functionality to add:

  • a range of output files. In addition to the base HTML, PDF, epub formats; a clear print PDF can also be produced (the most popular alternate format selected by disabled students in the Department of Mathematical Sciences).
  • support for numbered theorem, proof and other environments.

See the supporting ClavertonDown example book which demonstrates the functionality, documents usage and install instructions.

More Resources

Published bookdown examples

General Guidance

Printable Cheat Sheets