What is bookdown?
bookdown allows you to compile a range of accessible document formats from a markdown text file(s) source. Although Abookdown is a package to extend RMarkdown (which is uses the R programming language to compile documents), no in-depth knowledge or usage or R is required.
A key output format is an HTML document (the bookdown manual is an example of this), which allows:
- accessible display of mathematics with the maths equations rendered using MathJax.
- navigation controls (chapters, links to sections, references etc).
- display controls (night mode, text scaling and reflow to support mobile users).
- option to download in an alternative format (PDF, ePub, Word are also supported).
In terms of authoring, Equation syntax is the same as LaTeX. Referencing of figures/equations and citations (via bibtex), display and other commands are supported but the synax differs from LaTeX.
What’s ‘wrong’ with LaTex?
- 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).
There are LaTeX packages and tools that can transform a subset of LaTeX commands to HTML. While some of these do support Mathjax, there are sometimes other accessible features (e.g. support for alt-text).
There are many features that can make a document accessible. These include being able to – in some cases these are nice features to have or may be required by a students’ disability action plan.
Why use bookdown?
bookdown authoring advantages:
- You are compiling from source: a similar workflow to those familiar in working with LaTeX source.
- Maths syntax is same as LaTeX – this simplifies the workflow in converting existing notes.
- Easy and clean syntax to use, in contrast to verbose LaTeX markup. bookdown documents are plain text files that have content without detailed typesetting commands (document properties are controlled elsewhere in a separate .yaml file).
bookdown output advantages:
- You generate multiple output formats from a single source (HTML, PDF, beamer and presentation type outputs, Word, ePub).
- HTML output is easy to control the navigation and appearance (zoom/resize text, adjust colours/contrast and text reflow for mobile users).
- Add rich content to your course notes – you can be embed other content directly into the bookdown page (e.g. a video explanation or geogebra widget).
- Outputs can be accessed by a range of users.
How do I get started with 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) – optional
ClavertonDown for advanced users
ClavertonDown was created locally 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.
Additional Resources
Published bookdown examples
- RStudio’s RMarkdown Gallery showcases a collection of RMarkdown outputs.
- Relativistic Cosmology Part 2 (Scowcroft 2020)
- Foundation Chemistry – Mathematical Skills (Dickinson 2022)
- The power of the browser: embedding Desmos and other content (Lim 2022) (slideshow)