BookML

Automated LaTeX to bookdown-style HTML and SCORM, powered by LaTeXML.

BookML is a small wrapper around LaTeXML for the production of accessible HTML content straight from LaTeX files, and for packaging it as SCORM. Created by and maintained for maths lecturers at the University of Leeds. Its main features:

• simple installation: simply drop the bookml/ directory next to the files to be compiled and copy GNUmakefile in the same place (well, uhm, that is a bit of a lie: you need to install LaTeXML first!)
• accessible and mobile friendly output: virtually identical to the GitBook style of bookdown, including font selection and dark mode, tweaked to meet the Web Content Accessibility Guidelines 2.1 level AA
• fully automated (re-)compilation based on which files have changed on disk, powered by GNU make: just run

  make

  to zip together all PDF and HTML outputs from all the main .tex files in the directory (one package per main .tex file)
• high quality conversion of external EPS and PDF figures to SVG via dvisvgm, rather than ImageMagick used by LaTeXML
• transparent generation of SVG images from TikZ pictures, animate animations, Xy-matrices, and virtually any other picture-like environment: just add a few lines of code in the preamble

  \usepackage{bookml/bookml}
  \bmlImageEnvironment{tikzpicture,animate}
  \iflatexml\else % prevent LaTeXML from even trying to load TikZ
  \usepackage{tikz}
  \usepackage{animate}
  \fi

• alternative text for images straight from LaTeX:

  \usepackage{bookml/bookml}\bmlImageEnvironment{tikzpicture}
  ...
  \begin{tikzpicture} ... \end{tikzpicture}\bmlDescription{Textual description of the TikZ picture}
  % alt= option for \includegraphics requires LaTeXML 0.8.7
  \includegraphics[alt={Text description of the figure}]{figure}

• arbitrary HTML content in LaTeX, such as collapsible tags:

  \usepackage{bookml/bookml}
  ...
  \<details>
    \<summary>\textbf{Solution.}\</summary>
    To create a collapsible `proof' environment, ...
  \</details>

• declare alternative PDF versions (for instance sans serif, large print):

  \bmlAltFormat{PDF (large print)}{notes-large-print.pdf}
  % you must provide notes-large-print.tex

  the files will be automatically compiled and included in the 'Download' menu of bookdown (see the example for more info)
• SCORM support: running make creates valid SCORM.*.zip packages supported by most Learning Management Systems (if not, please submit an issue!)

Examples

• The Leeds BookML guide
• forall $x$: Calgary by Richard Zach
• Representation Theory. A Categorical Approach by Jan E. Grabowski
• Probabilidade by Leonardo T. Rolla and Bernando N.B. de Lima
• Some resources of REA-MECC

Getting started

Running locally on your device (via make)

1. Install the prerequisites.
2. Install/upgrade: unpack the latest BookML release and put the bookml/ directory next to your .tex files.
3. First time only: copy bookml/GNUmakefile next to your .tex files.
4. Run make (or gmake).

Or you can unpack the template to start with a working minimal example.

Prerequisites

• Perl
• LaTeXML (minimum 0.8.7, recommended 0.8.8 or later)
• for any image handling: the Perl module Image::Magick
• for BookML images (see bmlimage below): Ghostscript, latexmk, preview.sty, dvisvgm (minimum 1.6, recommended 2.7 or later)
• for automatic PDF, HTML, zip, SCORM packaging, EPS/PDF to SVG automatic conversion: GNU make, latexmk, zip, optionally texfot
• for autoconverting EPS images to SVG, when using GNU make: dvisvgm with Ghostscript
• for autoconverting PDF images to SVG, when using GNU make: mutool is the default and most reliable option; otherwise, BookML can try using any dvisvgm with Ghostscript before version 10.01.0, or dvisvgm minimum 3.0 with mutool

Running locally on your device (calling latexml, latexmlpost, latexmlc directly)

You can also run BookML as a simple addition to LaTeXML. You will lose some functionality, such as conversion of EPS and PDF figures to SVG and SCORM packaging.

1. Install the prerequisites.
2. Install/upgrade: unpack the latest BookML release and put the bookml/ directory next to your .tex files.
3. First time only: copy bookml/LaTeXML-html5.xsl next to your .tex files.
4. Add \usepackage{bookml/bookml} to each .tex file.
5. Run latexml, latexmlpost, or latexmlc as you normally would without BookML. You are responsible for recompiling PDF files and other alternative formats before running latexmlpost.

GitHub and Overleaf

BookML is also available as a GitHub action. Simply add the file .github/workflows/bookml.yaml to the GitHub repository, or to your Overleaf project, containing the LaTeX files to be compiled.

on: push
jobs:
  build:
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Compile with BookML
        uses: vlmantova/bookml-action@v1

When using Overleaf, you must also synchcronize your project with a GitHub repository (requires an Overleaf Pro account).

On every push, GitHub will compile every .tex file containing the string \documentclass, then create a GitHub release containing all outputs generated by BookML. You will receive an email from GitHub on completion, unless you have changed your notification settings.

Read the BookML action page for its configuration options.

Docker container

BookML is also available as a Docker image. To run it in the current directory, use

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

Please note that the image contains a complete copy of TeX Live 2021. For a smaller image, use one of ghcr.io/vlmantova/bookml-basic, ghcr.io/vlmantova/bookml-small, ghcr.io/vlmantova/bookml-medium, ghcr.io/vlmantova/bookml.

Reference manual

Package options

Certain options can be passed to BookML like with any other LaTeX packages, for instance \usepackage[mathjax=4]{bookml/bookml}. The following options are available:

style=<name>

Switch style. <name> can be gitbook (default), which is almost identical to the output of bookdown, plain, which is a tweaked version of the normal LaTeXML style, and none for the LaTeXML with compatibility and bug fixes only.

mathjax=<number>

Select which MathJax version to use from 2, 3 (default), 4.

nomathjax

Disable MathJax.

imagescale=X.XX

(Deprecated) Rescale all images generated via LaTeX (using bmlimage, see below) by the desired factor. Images are normally sized so that fonts inside the image match the font size of the browser, but there are cases where BookML is wrong, and images turn out too small or too large. When that happens, tweak imagescale.

nohtmlsyntax

Do not define the command \< used for writing HTML tags directly in TeX.

Package commands and environments

Loading \usepackage{bookml/bookml} makes the following commands available. It also loads the latexml package, which provides additional commands such as \iflatexml and \lxRequireResource.

\BookMLversion

The currently running version of BookML.

\bmlAltFormat[<opts>]{<file>}{<label>}

Compile (if necessary) and include <file> in the download menu with label <label>. An empty label removes the file from the download menu. The optional argument <opts> is a key-value list passed internally to \lxRequireResource (for instance, use type=application/octet-stream if LaTeXML is not able to recognise the MIME type of the file). Only available in the gitbook style.

\<

Open or close an HTML tag, as in \<span class="example">some \LaTeX{} code\</span>. The content between the tags is normal LaTeX code. Tags will normally generate an additional <p>...</p> tag, unless they can only contain 'phrasing content'. If necessary, the behaviour of each tag can be changed with the \bmlHTML*Environment commands.

\bmlHTMLEnvironment{<tag>}

Introduce or redefine an HTML tag environment \begin{h:<tag>}[attr1=val1,...]...\end{h:<tag>} and corresponding \<tag>.

\bmlHTMLInlineEnvironment{<tag>}

Introduce or redefine an HTML tag environment \begin{h:<tag>}...\end{h:<tag>} and corresponding \<tag> which accept phrasing content only.

\bmlRawHTML{<html>}

Insert <html> directly in the output document, after expanding all the TeX macros. When the command appears in the preamble, <html> will be part of the head and will be copied in every output page. <html> must be written in valid XML syntax, with either no namespace or the correct namespace for HTML.

\begin{bmlimage}

The body of this environment is compiled directly into an SVG image via LaTeX, instead of running through LaTeXML.

\bmlImageEnvironment{<env>}

Compile all environments <> directly into SVG images via LaTeX, instead of running the body through LaTeXML. A typical use is \bmlImageEnvironment{tikzpicture} for when LaTeXML struggles to process TikZ figures properly or sufficiently quickly. Warning: this will not work properly when the environments are called implicitly (for instance, the package tcolorbox uses \begin{tikzpicture} internally to implement its theorems).

\bmlDescription{<text>}

Attach an alternative text <text> to the immediately preceding object. Only useful for images, for instance immediately after \end{tikzpicture}. Warning: the command must immediately follow the object; even empty spaces can cause issues.

\bmlPlusClass{<class>}

Add the CSS class <class> to the immediately preceding object (this complements \lxAddClass and \lxWithClass provided by the latexml package). Warning: the command must immediately follow the object; even empty spaces can cause issues.

\bmlDisableMathJax

Disable running MathJax on the current mathematical content. When used in an environment that generates multiple equations, it applies only to the current one.

Makefile options

The build process accepts configuration options via Make variables, using the syntax VARIABLE=value. The options can be passed in three ways:

1. In GNUmakefile before include bookml/bookml.mk. Each option must appear on its own line, without indentation.
2. On the command line as make VARIABLE=value.
3. To apply an option to a single output file, write it in GNUmakefile after include bookml/bookml.mk as file: VARIABLE=value on its own line, without indentation. For instance, main.pdf: LATEXMKFLAGS=-pdflua. Warning: the variable must be applied to the target it affects immediately or it can cause inconsistent results (see for example SPLITAT below).

Note that changing options will not trigger a recompilation of the files. You will typically need to run make clean before recompiling again. For more information about the Makefile syntax and how variables are evaluated, consult the GNU Make manual.

The following options are available.

AUX_DIR

Location of the directory containing all intermediate files generated during compilation, such as .aux and .bbl files. This option is ignored by the BookML GitHub action. Default auxdir.

SOURCES

Space-separated list of .tex files to be compiled. File names with spaces are not supported. Default is the list of .tex files in the current directory that contain the string \documentclass (even if appearing in a comment!).

FORMATS

Spaces-separated list of formats to be generated from SOURCES. Recognised formats are pdf, scorm, zip. Default scorm zip.

SPLITAT

How to split the HTML output into multiple files (chapter, section, subsection, subsubsection). Set to empty to disable splitting. See the latexmlpost manual, --split option, for more details. Warning: when applied to a single target, it must be applied to $(AUX_DIR)/file/index.html: instead of say file.zip:, otherwise zip and SCORM outputs will see different values. Default section.

DVISVGM

Command to call dvisvgm. Default dvisvgm.

DVISVGMFLAGS

Options to pass to dvisvgm. Default --no-fonts.

LATEXMK

Command to call Latexmk. Default latexmk.

LATEXMKFLAGS

Command options to pass to latexmk. For instance, use LATEXMKFLAGS=-pdflua to use LuaTeX when compiling to PDF. Please ensure that latexmk will produce a PDF rather than a DVI.

LATEXML

Command to call LaTeXML. Default latexml.

LATEXMLFLAGS

Options to pass to LaTeXML.

LATEXMLPOST

Command to call latexmlpost. Default latexmlpost.

LATEXMLPOSTFLAGS

Options to pass to latexmlpost. Warning: when applied to a single target, it must be applied to $(AUX_DIR)/file/index.html: instead of say file.zip:, just like for SPLITAT.

MUTOOL

Command to call mutool. Default mutool.

MUTOOLFLAGS

Options to pass to mutool draw.

PERL

Command to call Perl. Default perl.

PDFTOSVG_CONVERTER

Select which converter to use for converting PDF images to SVG. Currently supported values are dvisvgm and mutool. If set to empty, LaTeXML will convert PDF to PNG using ImageMagick. Default mutool.

TEXFOT

Command to call tex. Default texfot.

TEXFOTFLAGS

Options to pass to texfot.

ZIP

Command to call zip. Default zip (or miktex-zip if zip.exe is not available on Windows).

Makefile targets

The following targets can be used as arguments when calling make, for instance make zip.

all

Compile all targets, based on the content of SOURCES, FORMATS, and TARGETS. This is the default target.

check-for-update

Check if there is a new release of BookML available.

clean

Delete all compilation products, based on SOURCES, FORMATS, and TARGETS.

detect

Detect the versions of all the software required to run BookML and print them.

html

Compile all SOURCES to HTML. The outputs will be in the $(AUX_DIR)/html directory.

pdf

Compile all SOURCES to PDF. The outputs will be in the current directory, including the SyncTeX files.

scorm

Compile all SOURCES to SCORM. The outputs will be in the current directory.

update

Experimental: update the bookml/ directory. If BookML is being run from a Docker image, it will use the version bundled in the image, otherwise it will download the latest release. This operation is destructive, not well tested, and behaviour may change in the future; be prepared to download BookML manually if it breaks.

xml

Compile all SOURCES to XML. The outputs will be in the $(AUX_DIR)/xml directory.

zip

Compile all SOURCES to zip. The outputs will be in the current directory.

Others

bml_no_invert

Applying this CSS class disable the color inversion of images in dark mode. This applies only to external images, such as EPS figures, or pictures converted using bmlimage. The class can be applied to the image itself or to a surrounding paragraph, section, environment, etc. using one of \lxAddClass, \lxWithClass, \bmlPlusClass.