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.
- LaTeX rendering equations to pdf does not support readers who rely on assistive technology (such as a screen reader, Braille) to access the document. Even if the individual characters can be read (not images), the semantics of equations is often lost.
- Typesetting to an A4 page doesn't support students who are viewing the document on a mobile device or need to zoom in and want the text to reflow.
- Although there is document structure in LaTeX (e.g. \section{}, \subsection{}, etc), these tags are not normally written when creating a PDF).
- LaTeX is Turing Complete: you can program with it as these examples, calculating the Fibonacci Sequence or controlling a Mars Rover, demonstrate! Given the open ended scope, it is non-trivial to transform LaTeX documents to make alternative formats (e.g. large print, screen readable, Braille formats, etc) to support all students, even with the use of "LaTeX conversion tools" (e.g. Pandoc, Tex4ht, MathAltNotes).
- For a more detailed discussion, please see LaTeX is NOT Easy: Creating Accessible Scientific Documents with R Markdown (Seo 2019).
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)?
- 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).
- Authoring Books and Technical Documents with R Markdown (Xie 2020) gives detailed documentation on the bookdown package for authors.
- Please also join the bookdown usergroup on Microsoft Teams, where staff can share their experiences, issues and solution with using Rmarkdown and bookdown.
- 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
- RStudio's RMarkdown Gallery showcases a collection of RMarkdown outputs.
- Relativistic Cosmology Part 2 (Scowcroft 2020)
General Guidance
Printable Cheat Sheets
Themes
- Accessibility
Guidance
Writing Accessible Technical Content
Accessible maths with Microsoft Equation Editor Guidance
Accessible maths with RMarkdown Guidance
Accessible maths with Moodle Guidance
UK Professional Skills Framework
Contacts
For advice on implementing this guidance to enhance learning, teaching and assessment contact the TEL team: tel@bath.ac.uk