The Leeds BookML guide

Vincenzo Mantova

21st January 2026

This is a short manual on how to install and run BookML at the University of Leeds, accompanied by some general tips about improving the accessibility of your documents. For further instructions about BookML, including explanations about TikZ, alternative text, videos, and so on, please consult the BookML manual.

1 Installation

1.1 Prerequisites

Full list of prerequisites
  • •
    ​

    (minimum 0.8.7, recommended 0.8.8 or later)

  • •
    ​

    Any image handling: the Perl module Image::Magick

  • •
    ​

    Support for converting EPS, PDF images to SVG: Ghostscript, dvisvgm for EPS; mutool for PDF (you can also configure BookML to use dvisvgm instead of mutool, but it is less reliable)

  • •
    ​

    BookML images: Ghostscript, latexmk, preview.sty, dvisvgm (minimum 1.6, recommended 2.7 or later)

  • •
    ​

    Automatic PDF, html, and zip creation: GNU Make, latexmk, zip, optionally texfot

The packages latexmk, preview.sty, dvisvgm and texfot are distributed by MiK, Live, and virtually all Linux distributions.

For the rest of the software, follow the instructions below.

Overleaf
  • •
    ​

    First time only. Open your Overleaf account settings and link your GitHub account from the ‘GitHub Sync’ entry.

  • •
    ​

    Open an existing or new Overleaf project and start synchronizing it with a new GitHub repository. The process is smoother when the project name has no spaces. Note: I recommend you immediately visit the new repository and click the ‘Watch’ icon (next to ‘Edit Pins’, ‘Fork’, ‘Star’).

  • •
    ​

    Finally, add the file .github/workflows/bookml.yaml to the project with the following content:

    ⬇
    on: push

jobs:

  build:

    runs-on: ubuntu-latest

    permissions:

      contents: write

    steps:

      - name: Compile with BookML

        uses: vlmantova/bookml-action@v1

    Now synchronize the project with GitHub. First time only: GitHub will ask you to grant permissions to Overleaf to run workflows. Say yes!

  • •
    ​

    GitHub should start compiling all .tex files at the top folder of your Overleaf project that contain the string \documentclass (even if commented out!). The work is done by the BookML Docker image, which at the moment contains a full copy of Live 2021.

  • •
    ​

    If you ‘watched’ the repository as recommended in the previous steps, you should receive an email in 2–3 minutes with the download links of all the outputs compiled by BookML and any relevant error messages. If you do not watch the repository, you must visit the repository page yourself and look for new entries under ‘Releases’ (below ‘About’) or open the latest workflow run under the ‘Action’ tab.

  • •
    ​

    Every time you want to compile a new version of your Overleaf project, just push the new changes to GitHub.

GitHub
  • •
    ​

    Simply add the file .github/workflows/bookml.yaml to your repositories with the following content:

    ⬇
    on: push

jobs:

  build:

    runs-on: ubuntu-latest

    permissions:

      contents: write

    steps:

      - name: Compile with BookML

        uses: vlmantova/bookml-action@v1

    I also recommend that you watch the repository (this is usually automatic when you create a repository; see the ‘Watch’ icon on the repository page, next to ‘Edit Pins’, ‘Fork’, ‘Star’).

  • •
    ​

    GitHub should start compiling all .tex files at the top folder of your repository that contain the string \documentclass (even if commented out!). The work is done by the BookML Docker image, which at the moment contains a full copy of Live 2021.

  • •
    ​

    If you are watching the repository as recommended in the previous steps, you should receive an email in 2–3 minutes with the download links of all the outputs compiled by BookML and any relevant error messages. If you do not watch the repository, you must visit the repository page yourself and look for new entries under ‘Releases’ (below ‘About’) or open the latest workflow run under the ‘Action’ tab.

  • •
    ​

    Every push will start a new compile. If you push frequently, consider tweaking the action to run only when pushing to specific branches or tags.

macOS (MacPorts)
  • •
    ​

    Open the Terminal app.

  • •
    ​

    Run xcode-select --install to get the Command Line Developer Tools.

  • •
    ​

    Install MacPorts as per its official instructions from point 2 (no need for full Xcode!).

  • •
    ​

    If your was installed via Mac, run:

    ⬇
    sudo port install gmake LaTeXML +mactex

    For the Ghostscript and mutool prerequisites, depending on your specific version of Mac, you may need to install the Ghostscript-Extras package.

    Otherwise

    ⬇
    sudo port install gmake LaTeXML

    For the remaining prerequisites (such as dvisvgm), add them as you would add any other Live package (for instance using the Live Utility).

    Ghostscript-Extras will include mutool, but if it is still not available on your system and you use PDF images, run

    ⬇
    sudo port install mupdf
  • •
    ​

    If, and only if, your was installed via MacPorts, you can add the optional packages via:

    ⬇
    # for automatic PDF, html, zip creation

sudo port install dvisvgm latexmk

# for BookML images (preview.sty)

sudo port install texlive-latex-extra

# for texfot (to reduce latex output during PDF creation)

sudo port install texlive-bin-extra

# for PDF to SVG conversion (normally already installed at this point)

sudo port install mupdf
  • •
    ​

    To upgrade:

    ⬇
    sudo port selfupdate

sudo port upgrade outdated
  • •
    ​

    The remaining packages (e.g. GNU Make) are already available.

macOS (Homebrew) – AVOID PLEASE

The Homebrew version has intrinsic packaging issues and should be avoided. However, if you really insist:

⬇
brew install latexml make

Functionality related to images will likely be broken.

Linux Debian-based (Ubuntu, Debian, Mint, etc)

Download the package for the latest Ubuntu releases at https://launchpad.net/ubuntu/+source/latexml. Install ghostscript, make, latexmk, dvisvgm, preview-latex-style, texlive-extra-utils (for texfot), zip, according to your needs.

⬇
sudo dpkg -i latexml_0.8.8-1_all.deb

sudo apt -f install

sudo apt install ghostscript make latexmk dvisvgm preview-latex-style texlive-extra-utils zip

# for PDF to SVG conversion (normally already installed at this point)

sudo apt install mupdf-tools
Linux RPM-based (Red Hat, CentOS, AlmaLinux, etc)

Not figured out yet!

Linux School PC (presumably only desktop connected via cable)

Run the following each time you open a new terminal:

⬇
module load latexml

module load texlive

If it does not work, run the following command and try again:

⬇
module use /apps/linsw1/modulefiles/7/

Everything else should already be available. Please contact IT if you are still on an old version of (that is, before 0.8.8).

Windows (AppsAnywhere — easiest)

Changed on January 2026. Due to an unresolved issue with CloudPaging Player, the instructions below are a little different now.

  • •
    ​

    Make sure to have AppsAnywhere installed.

  • •
    ​

    Install Ghostscript, ImageMagick, MiK, StrawberryPerl.

  • •
    ​

    Open a terminal and install mutool:

    ⬇
    winget install mutool
  • •
    ​

    Open a terminal, or StrawberryPerl, and run:

    ⬇
    llw32helper.bat

    Answer ‘y’ to the first question, and just press Enter on the second question (or choose a different folder if you wish to). Warning: running llw32helper a second time will ask you about undoing what it just did. Only run it once!

    Now close and reopen the terminal and continue with the following.

    ⬇
    cpanm --build-args=CC=c++ --notest --verbose Image::Magick

cpanm --notest --verbose LaTeXML

Everything else should then be available. Re-do the cpanm steps to update. You may have to reinstall the apps every one or two months (open the CloudPaging Player to check their status), but you will not need to reinstall .

Windows (with admin rights)

For University laptops: you can gain admin rights by right-clicking an the installer and choosing “Request Run as Administrator”.

  • •
    ​

    Install StrawberryPerl 64bit version.

  • •
    ​

    Install ImageMagick x64-dll. During installation, enable ‘Install development headers and libraries for C and C++’:

    [Uncaptioned image]

    Be very careful not to choose 32bit, portable, or static variants.

  • •
    ​

    Install Ghostscript 64bit.

  • •
    ​

    Open a terminal and install mutool:

    ⬇
    winget install --scope=machine mutool
  • •
    ​

    In StrawberryPerl, run

    ⬇
    cpanm --build-args=CC=c++ --notest --verbose Image::Magick

cpanm --notest --verbose LaTeXML

Everything else should then be available. Re-do all of the above to update.

Windows (without admin rights)

Install the Scoop package manager (no admin required). Then run:

⬇
scoop install perl

Now launch ‘Edit environment variables for your account’, double click or ‘PATH’, and add %USERPROFILE%\scoop\apps\perl\current\c\bin. Close and reopen the terminal and check whether you can run gmake now. If you succeed, run:

⬇
scoop install imagemagick

scoop install ghostscript

cpanm --build-args=CC=c++ --notest --verbose Image::Magick

cpanm --notest --verbose LaTeXML

For PDF to SVG conversion, run:

⬇
winget install mutool

Everything else should then be available. Use scoop update --all to update.

Docker/Podman/etc

You can also run BookML using Docker. The default image will compile automatically all the content of the /source folder. For instance:

⬇
docker run --rm -i -t -v.:/source ghcr.io/vlmantova/bookml

Please note that the Docker image includes a full copy of TeX Live 2021.

1.2 BookML

Unzip the template.zip file from the latest BookML release. Open a terminal in the folder containing Makefile, template.tex, and run

⬇
make detect  # for Linux

gmake detect # for macOS, Windows
How do I run commands in the terminal?

You simply type them and press <ENTER>. To open the terminal in a specific folder:

Windows

Right click on a folder and select “Open in Windows Terminal”. If the option is missing, try (re)installing it via

⬇
winget install --id Microsoft.WindowsTerminal -e
macOS

Right-click on a folder and select “New Terminal at Folder”.

Linux

Many file browsers have an option “Open in Terminal” when you right-click on a folder.

Use gmake detect on Windows. You should get something like the following:

Main files: template.tex
BookML: v0.25.1 OK
GNU Make: 4.4.1 OK
TeX: MiKTeX 25.4 OK
perl: v5.42.0 OK
LaTeXML: 0.8.8 OK
Image::Magick: NOT FOUND (required for any image handling)
Ghostscript: 9.25 OK (required for BookML images, EPS to SVG; may be required for PDF to SVG)
mutool: 1.23.0 OK (required for PDF to SVG if using PDFTOSVG_CONVERTER=mutool (current value ‘mutool’))
dvisvgm: 3.4.3 OK (required for BookML images, EPS to SVG, PDF to SVG if using PDFTOSVG_CONVERTER=dvisvgm (current value ‘mutool’))
dvisvgm/libgs: 9.25 OK (required for BookML images, EPS to SVG, PDF to SVG if using PDFTOSVG_CONVERTER=dvisvgm (current value ‘mutool’))
latexmk: 4.87 OK
texfot: 1.48 OK (optional, for hiding some LaTeX messages)
preview.sty: 14.0.6 OK (required for BookML images)
zip: 3.1b OK
curl: 8.13.0 OK (required for updating with ‘make update’)

Anything missing will show a red NOT FOUND. If the version is too old, there will be a red or a yellow prompt to upgrade.

First try? Run make (or gmake on macOS, Windows). After a bit, you will find a folder template and two zip files template.zip, SCORM.template.zip. Please open template/index.html and verify that it looks as you would expect. The zip files are set up for upload on Minerva.

To update BookML, run make check-for-update, then make update, simply replace the bookml folder with the content of a newly downloaded release.zip.

2 Converting your files

2.1 How to convert

Once your are satisfied that the template is working, drop your own files next to template.tex: each file containing \documentclass will be treated the same as template.tex, and will be compiled to PDFs, SCORM and zip packages. Run make detect again, and check that ‘Main files’ contains such new files.

There is now a reasonable chance that your files are already working (unless you are using TikZ, which needs some care), but before your first try, you should truncate your files with an early \end{document}, as compilation times can be long and most errors will originate in the preamble anyway.

To compile, do the following:

  • •
    ​

    Run

    ⬇
    make

    On Windows, it is gmake rather than make.

    After a bit, you will have files named like lecturenotes.zip, SCORM.lecturenotes.zip. The former works with ‘Upload Zip package’; the latter with ‘Create SCORM package’.

    To generate one particular package, for instance the one for the file lecturenotes.tex, run

    ⬇
    make lecturenotes.zip

    or, if you are using SCORM packages,

    ⬇
    make SCORM.lecturenotes.zip
  • •
    ​

    When you change a file and want to regenerate the zip files, just run make again. Only the files that need updating will be recompiled.

  • •
    ​

    If you start getting strange error messages from make itself, consider deleting the auxdir folder and try again.

What is make doing? Step-by-step look under the hood

Each time you call make, it does the following.

  1. 0.
    ​

    Read the file Makefile in the folder you are in. That file will import instructions from the bookml folder about what to do next.

  2. 1.
    ​

    Check all .tex files in the folder and find the ones containing \documentclass.

    In example.zip, it finds main.tex and secondfile.tex.

  3. 2.
    ​

    Arrange to generate two ‘targets’, a zip package and a SCORM package, for every such file in step 1.

    In the example, the targets are main.zip, SCORM.main.zip, secondfile.zip, SCORM.secondfile.zip.

  4. 3.
    ​

    Check if the targets of step 2 exist, and if so, if any of their ‘prerequisites’ are newer, in which case the targets must be updated. The prerequisites themselves are checked recursively to see if they also need to be updated. The prerequisite chain looks like ‘zip => html => xml => pdf => tex’.

    In the example, on your first try, Make will follow the following prerequisite chain: main.zip => main/index.html => main.xml => main.pdf => main.tex. It will then build the prerequisites backwards until all is in place to create main.zip. Likewise for the other targets.

  5. 4.
    ​

    Build the PDF of each file found in step 1, using latexmk to run pdflatex, makeindex, bibtex and similar as many times as necessary; record which files are \input’d and mark them as prerequisites for step 3.

    In the example, it builds main.pdf, secondfile.pdf, and marks chapter1.tex as prerequisite of main.pdf. Any update to chapter1.tex will cause main.pdf to be updated next time you call make.

  6. 5.
    ​

    Call to build an xml file from each file in step 1.

    In the example, main.xml, secondfile.xml.

  7. 6.
    ​

    Try to build or update the alternative formats requested using \bmlAltFormat. For now, BookML only knows how to build PDF files from files that have the same name; if you need other formats, you need to build them yourself, or add the relevant instructions (called ‘recipes’) in the Makefile.

    In the example, main-sans.pdf and main-sans-large.pdf are the alternative formats requested in the preamble of main.tex, on top of main.pdf which has been built already. Since the example contains main-sans.tex, main-sans-large.tex, BookML will know what to do, and generate the alternative PDFs by repeating step 4.

  8. 7.
    ​

    Convert the xml files to html, using latexmlpost.

    Thus generate the folders main, secondfile, each containing an index.html.

  9. 8.
    ​

    Zip the folder and pack the SCORM package (the latter requiring a couple more steps I will not explain), using zip

    At last, you will get main.zip, SCORM.main.zip, secondfile.zip, SCORM.secondfile.zip.

2.2 Necessary adjustments

Consult template.tex for the minimal requirements in the preamble (e.g. you must provide a \title command). You should create copies of template-sans.tex, template-sans-large.tex for each of your main files, at least as a baseline. Alternative versions can be customized and removed, as explained in the next subsection. We recommend offering some alternative versions as good practice.

You should also follow the key requirements below.

  • •
    ​

    Use the babel package to set the document language (crucial for screen readers to work correctly). For instance:

    ⬇
    \usepackage[british]{babel}
  • •
    ​

    Set the document metadata in the preamble (essential for proper navigation links, web page titles, SCORM package metadata, and so on).

    ⬇
    \title{LaTeXML + BookML guide}

\author{Vincenzo Mantova}
  • •
    ​

    Ensure all style formatting commands (\Large, \bf, …) are enclosed between braces, and use alternatives such as \textbf{} when possible. If you see the wrong font in the html output, it is likely caused by -style font switches that haven’t gone well.

    ⬇
    {\bf some bold text}    % DO

\bf some bold text      % DON'T

\textbf{some bold text} % BEST
  • •
    ​

    Using TikZ or XY-pic and an old version of (before 0.8.7), or getting misaligned pictures and very long compile times? Use the bmlimage feature (see the BookML manual for more info).

2.3 Alternative formats

This is not required, but it is good to be ready to include alternative versions of the PDF as well, for instance a large print version. For instance, add the following to the preamble of lecturenotes.tex:

⬇
\usepackage{bookml/bookml} % if not already in your preamble

\bmlAltFormat{lecturenotes.LARGE.pdf}{PDF (large print)}

and create a corresponding lecturenotes.LARGE.tex that

  • •
    ​

    does NOT contain \documentclass (or it will be compiled into its own SCORM and zip packages);

  • •
    ​

    configures e.g. different fonts and margins, then call \input{lecturenotes.tex}.

BookML will automatically compile and include lecturenotes.LARGE.pdf in your final outputs.

Consult template.tex, template-sans.tex, template-sans-large.tex for some simple techniques.

If you instead want distinct SCORM and zip packages, for instance compile a problem sheet both with and without solutions, explore example.zip to see some possibilities.

2.4 Other adjustments

Please peruse the BookML manual for several suggestions, ranging from how to write foldable environments, embed videos and animations, deal with very slow or broken TikZ pictures, and so on.

3 Uploading to Minerva

3.1 SCORM packages

  1. 1.
    ​

    On the front page of your module, under ‘Module content’, click the ⊕\oplus button where you want to insert your item.

  2. 2.
    ​

    Choose ‘⊕\oplus Create’.

  3. 3.
    ​

    Choose ‘SCORM package’.

  4. 4.
    ​

    Choose ‘Upload SCORM package’ and select your SCORM.<...>.zip file.

  5. 5.
    ​

    Disable ‘Grade SCORM’ and click ‘Save’.

Note. Title and abstract of the file will become title and description of the Minerva entry. A better way to prepare the description is to use

⬇
\usepackage{hyperref}

\hypersetup{pdfsubject={Description of this SCORM package}}

You will be able to edit the Minerva details right after uploading, if necessary.

3.2 Plain ZIP packages

For the initial permission setup, as well as screenshots of the entire process, consult Chris’ guide.

Below is a summary of the day-to-day upload process, once permissions have been set up:

  1. 1.
    ​

    On the front page of your module, under ‘Module content’, click the ⊕\oplus button where you want to insert your item.

  2. 2.
    ​

    Choose ‘Content Collection’, then ‘Browse Content Collection’.

  3. 3.
    ​

    Browse to the folder that has been set up with the appropriate permisions.

  4. 4.
    ​

    Click ‘Upload’ and choose ‘Upload Zip Package’.

  5. 5.
    ​

    Use ‘Browse Local Files’ to upload your <...>.zip file. You must enable ‘If selected, the system automatically overwrites the existing file with the same name’.

  6. 6.
    ​

    Click ‘Submit’, the choose ‘index.html’ as file to be presented on Minerva.

4 Some examples

To compute 2+3, add a copy of the well ordered set 3 after the well ordered set 2, and note that the result is isomorphic to the well ordered set 5.
To compute 2+3, add a copy of the well ordered set 3 after the well ordered set 2, and note that the result is isomorphic to the well ordered set 5. 22++33==55011++01122==011223344
Figure 1: Ordinal sum of 22 and 33 generated in two ways: first via ‘bmlimage’, then directly by . The latter uses MathJax for the embedded formulas, resulting in improved accessibility but minor alignment issues.
A, B, C drawn in a triangle with C under B, an arrow labelled phi from A to B and an arrow from A to C
A, B, C drawn in a triangle with C under B, an arrow labelled phi from A to B and an arrow from A to C A{A}B{B}C{C}ϕ\scriptstyle{\phi}
Figure 2: Example of tikzcd diagram, again generated in two ways via ‘bmlimage’ and directly by .
⬇
\begin{bmlimage}

  \[ \xymatrix{

        A \ar[rd] \ar^\phi[r] & B \\

                              & C } \]

\end{bmlimage}

\bmlDescription{A, B, C drawn in a triangle with C under B,

  an arrow labelled phi from A to B and an arrow from A to C}
Example of X
Figure 3: Example of XY-matrix diagram processed using bmlimage.
A\textstyle{A\ignorespaces\ignorespaces\ignorespaces\ignorespaces\ignorespaces% \ignorespaces\ignorespaces\ignorespaces}ϕ\scriptstyle{\phi}B\textstyle{B}C\textstyle{C}
Figure 4: Unsatisfying example of XY-matrix generated directly by .
⬇
% preamble

\newcommand{\youtube}[2]{\bmlRawHTML{<iframe

  src="https://www.youtube-nocookie.com/embed/#1"

  title="#2" frameborder="0" allow="picture-in-picture; web-share"

  referrerpolicy="strict-origin-when-cross-origin" allowfullscreen=""

  style="width:100\%;max-width:1920px;aspect-ratio:16/9"></iframe>}

  Watch \href{https://www.youtube.com/watch?v=#1}{#2}}

% document

\youtube{pTqBXcUPDug?si=tfkXijIyz4dgB38Z}{SCORM upload to Blackboard Learn Ultra}

Watch SCORM upload to Blackboard Learn Ultra

Figure 5: How to embed a video. Note that the special characters are preceeded by a backslash or the output may be invalid.
⬇
\begin{tabularx}{\textwidth}{c|X||c}

  \lxBeginTableHead{} Header 1 & Header 2 & Header 3 \\

  \hline \lxEndTableHead{}

  Content & Content & Content \\

  More content & content & content \\

  \hline

\end{tabularx}

\caption{A table}
Header 1 Header 2 Header 3
Content Content Content
More content content content
Figure 6: Mark a table row as header. Read the content of latexml.sty for more table-related commands.