Using bookdown to generate accessible course materials

Dr Thomas Cottrell (Department of Mathematical Sciences) shares his experiences of using bookdown, rather than LaTeX, to generate accessible course notes and problem sheets. This approach has many benefits to all students, but also brings some additional challenges. 

Background context 

As part of the legal requirements for accessibility, documents need to be digitally accessible. There needs to be adequate provision for all readers to engage with all content, including equations and formulae, images, diagrams, plots be it unassisted, or via assisted technologies (such as screen readers and electronic braille). 

Additionally, the concept of accessible design ensures that everyone can engage with content easily, which can also bring benefits to all learners. 

In the Department of Mathematical Sciences, Dr Thomas Cottrell teaches the first year Methods and Applications module, and a third-year course on Projective Geometry. Thomas has been using a variant of bookdown (ClavertonDown) as an alternative to creating lecture notes, problem sheets and solutions with LaTeX generated pdfs. 

Thomas has used LaTeX since 2008 and created and maintained many documents using the format. For the 2020/21 academic year Thomas converted his pdf lecture materials to html pages, from which students can download pdf versions if they desire. 

Why switch from LaTeX? 

If you have tried to copy and paste an equation from a LaTeX generated pdf document, you may have noticed it can often get jumbled up. When using assisted technologies such as screen readers, this same problem occurs. 

HTML versions of documents created with MathJax (a plugin developed by the American Mathematical Society) creates formulae which can be read clearly with and without assistive technologies, whilst being typed using the same LaTeX syntax (albeit with a limited number of LaTeX packages). 

It also allows for a smoother viewing experience on a mobile device, and for users who need to zoom in and want the text to reflow. 

Raw LaTeX code (and pdfs generated by them) only tells you what symbols you have and how you’d arrange them on a page. The semantics of equations often ends up being lost, and in the case of pdfs not accessible.

Why write in bookdown? 

It has to be said that bookdown doesn’t solve all these problems, especially when one symbol is used for multiple contexts. It can, however, create multiple formats from one source (e.g. an html webpage with the maths rendered html webpage from which students can download the version of their choice. 

Above: Lecture notes in a web browser and viewed in night mode on a mobile phone. There are options at the top of the page for hiding and revealing the navigation pane, searching the document, changing the text and background styles, and downloading in different formats. 

The html format is much more suited to digital displays than pdf. You can easily change to dark mode, resize the text, display in different orientations, screen sizes, etc., in addition to being useable with screen-readers. This can benefit students with particular sight or cognitive processing issues and all students viewing documents digitally.  When printing documents, a pdf document is the natural choice, and so that can be provided in addition to the html version. 

Thomas recalls the pre-Covid world where students in tutorials or help sessions at MASH would often attend without physical copies of problem sheets or lecture notes, or a laptop to view the pdf version. They would commonly use their phones to zoom in and out of pdfs which were designed to be printed in A4. Thus, html versions can often be more convenient for all users. 

Above: The same section of the lecture notes viewed on a mobile device in the html and pdf outputs. Notice the large amount of white space surrounding the text in the latter. 

The bookdown writing process 

Thomas created the documents manually, copying and pasting from his LaTeX notes, and then changing accordingly. This meant some upfront time investment, particularly for the first set of lecture notes, but it was much smoother for the second set, once he had learned how bookdown worked. Whilst there are automated ways of converting .tex files to bookdown documents,  some post-processing and tidying may still be needed, and these may not lead to the same level of familiarity with the language. 

Some of the more time-consuming elements included converting numbered or bullet-pointed lists into the markdown lists used in bookdown, and converting figures. Depending on the level of familiarity with R, one can create diagrams using R code. Whilst bookdown doesn’t support many LaTeX packages, Thomas notes that it is possible to use TikZ for diagrams, although he found the results unsatisfactory. 

There were a couple of typos or mistakes in the materials, and with the bookdown workflow it is quick to make these changes and update all versions simply too without resorting to the command line. 

Downsides of using bookdown 

Thomas pointed out a number of negatives: 

• There is limited formatting within markdown itself, as the nature of the language is to have the raw text look like a document. Thus, there is limited control of typesetting elements of design, such as page breaks, which may be viewed as a positive or a negative.
• A mixture of different languages are used by bookdown (R, RMarkdown, Markdown, LaTeX), with additional, separate commands. This can mean you need to learn little bits of each. 
• This is also the reason why comments in the bookdown file can be problematic. # can be a heading or a comment depending on which environment you are in (R/RMarkdown). Comments can be created with html tags, but due to the nature of comments in html files, they would be readable by inspecting the source. This could however lead to fun easter eggs in the notes.
• ClavertonDown (a project being worked on by Emma Cliffe in MASH) fixes several of Thomas’s issues with numbering and custom environments.
• The main challenge is that the bookdown user base is relatively small and new compared with that for LaTeX. LaTeX has many years of history. Hacks, packages and solutions to almost any problem can be found with some googling or asking on StackExchange. That said, colleagues across the university can offer solutions to questions, and provide advice and tips on the bookdown usergroup on Microsoft Teams. 

Recommendations 

• Give yourself time; don’t try and do it quickly. The effort will pay off.
• You must provide html, but you’d be mad not to do a pdf version as well. If there is demand you can later add epub or docx versions, too. This may take some additional tweaks.
• Join the bookdown usergroup on Microsoft Teams to ask for help. For example you can see this resource on Making Lecture Notes with Bookdown created and kindly shared by Dr Vicky Scowcroft (from the Department of Physics).
• If you care about numbering, custom environments, or marking the scope of the environment you can “upgrade” to ClavertonDown - but starting with bookdown and then changing is fine.