This post is about creating and publishing accessible lecture notes using bookdown. I converted my unfinished first year algebra course notes to bookdown format and uploaded the results.

I had a lot of hopes for this because it is based on markdown (small, easy to use), has LaTeX and MathJax support, and adds extensions (e.g. numbering for sections, equations, theorems) to vanilla markdown that are essential for all but the shortest math tests. The markdown parsing is a bit quirky (e.g. if you have a list at the start or end of an environment, it must be preceded or followed by two completely empty lines). Another example is that if you begin a proof environment that doesn’t start with a list with a blank line, you’ll generate a no line here to end error and it won’t even give you a line number for the generated tex file. Spaces after the final dollar sign in an inline math environment also cause errors.

Converting existing LaTeX files into markdown takes time although you can use Vim macros (or your local equivalent) to speed it up a bit. Debugging LaTeX errors is next to impossible so far as I can see: RStudio shows the usual cryptic LaTeX errors (sometimes even without a line number, though you can always find that in the log file), but the line number refers to the tex file generated from your markdown files so you have to look that up and then search your markdown files to find where the error is…

If your notes have a lot of equations then pages can be very slow to load. If your output is bookdown::gitbook you can mitigate this by adding

split_by: section+number

to _output.yml below the css: line. Then each section within each chapter gets its own html file.

You now face the problem that your LaTeX macros from the preamble.tex file aren’t visible to MathJax. One solution is to copy all the newcommands to the top of each markdown chapter file (changing to renewcommand otherwise tex will complain when you compile the pdf version of your book), but I’m not sure this will work if you are using split_by: section+number (maybe you could copy them after every section command…). Better to create a file mathjax_header.html which contains your macros, inside a \(...\), inside a <span class="math inline">. Then edit _output.yml again to add

includes:
      in_header: mathjax_header.html

(directly under your split_by: line will be OK). Adding the include to the preamble in the index.Rmd file didn’t work for me. It’s probably best to add another script changing the line break behaviour to work better in a mobile browser, but I didn’t try this.

To publish you can copy the _book folder (or whatever you have the output directory set to) direct to your web space.

Results

The output looks great, including in a mobile browser, and the toolbar works well. The search tool is useful, especially if you haven’t made an index. It really was a chore to convert from tex files and then debug though. People with experience with R Markdown would find it easier, and I suppose it would improve once you memorized the syntax for links and such like.

Even with the chapters split into one html file per section loading can be slow - this is inherent to client side math rendering and not the fault of bookdown. Being forced to split things into small chunks for usability might even be a good thing.

Accessibility:

  • :+1: MathJax
  • :+1: you can customize font size, serif/sans, and background colour in the toolbar
  • :-1: low contrast on the title that appears when you hover at the top (maybe configurable, I didn’t look)
  • :-1: there are keyboard shortcuts for search and hiding the toolbar but not for the other toolbar options (unless you’re using cVim or equivalent, but that will mask the built in keyboard shortcuts)

Overall I’m cautiously positive, but I’d like to have a proper go at PreTeXt to compare them. The built-in Sage consoles seem a great feature.