3 Reference manual

This section follows closely the reference manual on the BookML repository, but may lag behind new versions.

3.1 Package options

BookML can be configured by loading the bookml/bookml package and passing options to it 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 default LaTeXML style with minimal 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 have been cases where BookML is wrong, and images turn out too small or too large. When that happens, tweak imagescale, and please report the issue.
nohtmlsyntax: Do not define the command \< used for writing html tags directly in TeX.

3.2 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. Tags must follow the XML syntax, for instance \<br> is not valid: you must write \<br/>.
\bmlHTMLEnvironment{<tag>}: Introduce or redefine an html tag environment, to be used as \begin{h:tag}[attr1=val1,...]...\end{h:tag} or as \<tag>.
\bmlHTMLInlineEnvironment{<tag>}: Introduce or redefine an html tag environment which accepts ‘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 <env> directly into SVG images via LaTeX, instead of running them through LaTeXML. The most typical example is \bmlImageEnvironment{tikzpicture} for when LaTeXML struggles to process TikZ pictures 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, and that could results in theorems appearing as images, and in the wrong places).
\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.

3.3 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 somewhere 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.
PERL: Command to call Perl. Default perl.
TEXFOT: Command to call texfot. 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).

3.4 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.

3.5 Custom css

The css files in the folder bmluser are automatically included at the end of the <head> tag and will override the previous styles.

If the file name ends with .style1,style2-jobname.css, then that file will be used only when style=style1 is passed, or when style=style2 is passed and the main file being compiled is called jobname.tex. You can use ._all.css to ensure that the file is included in every style.

Custom css can also be added using \bmlRawHTML{<style> ... </style>} to the preamble.

For instance, the plain version of this manual has been compiled with latin-modern.plain.css that sets the font to Latin Modern.

3.6 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.

3.7 Options for the BookML GitHub action

Below is the list of arguments recognised by the BookML GitHub action. The list may be incomplete; see the BookML action page for details about the latest version.

checkout: Whether to checkout the repository calling this action. Default: true (boolean).
release: Whether to create a release containing the outputs generated by BookML. Default: true (boolean).
upload-aux-directory: Whether to upload the entire aux directory, which contains all outputs generated by BookML as well as logs and other intermediate files, into a GitHub artifact attached to the workflow run. Default: true (boolean).
scheme: Select which TeX Live scheme to use among basic, small, medium, full. Default: 'full' (string).
version: Select which version of BookML to use. Note that this only affects which Docker image is used; if the bookml/ folder is already present in the repository, that version of BookML will be used. Default: 'latest' (string).
replace-bookml: Whether to replace the bookml/ folder with the one included in the Docker image. Default: false (boolean).
timeout-minutes: The maximum number of minutes to run BookML before cancelling the build. Default: 6 (positive integer).

The action has the following outputs.

outputs: File names of all outputs compiled by BookML.
targets: File names of all targets that BookML tried to compile.
outcome: Compiling outcome (one of 'success', 'failure', 'timeout', 'invalid', 'cancelled').
aux-directory-url: URL of GitHub artifact containing the aux directory (only if upload-aux-directory is true).
release-url: URL of GitHub release (only if release is true).