1 Getting started

1. 1.
   ​

   Install the bare minimum prerequisites: LaTeXML (minimum 0.8.7, recommended 0.8.8 or later) and GNU Make (minimum 3.81, but later versions are considerably faster), on top of a working TeX installation, such as TeX Live or MiKTeX.

2. 2.
   ​

   Unpack the latest BookML release and put the bookml folder next to your .tex files. You can also start with a minimal template.

3. 3.
   ​

   First time only: move bookml/GNUmakefile one folder up. It must be in the same folder as your main .tex files.

4. 4.
   ​

   Now open a terminal in the folder containing GNUmakefile and run make detect (use gmake detect on Windows).

When all goes well, you should see an output like the following:

The first line shows which files BookML will try to compile: every .tex file in the current folder that contains the string \documentclass (even if commented out!). The rest informs you on which software you may need to install or update. Not everything is necessary: the output of make detect will tell you what functionality requires a particular program. The Leeds BookML guide has detailed installation instructions for various platforms, many specific to the University of Leeds.

Finally, run make (or gmake on Windows). BookML will compile each ‘main file’ to a zip file and a SCORM package. You can view the results in the folder auxdir/html.

Tip: the first time you run BookML against a new document, add an early \end{document}, say after one or two pages, to check whether LaTeXML is handling well your selection of packages and macros.

If you have a paid Overleaf plan, you can also compile your Overleaf project on GitHub’s servers.

1. 1.
   ​

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

2. 2.
   ​

   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’).

3. 3.
   ​

   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!

4. 4.
   ​

   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 TeX Live 2021.

5. 5.
   ​

   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.

6. 6.
   ​

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

1. 1.
   ​

   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’).

2. 2.
   ​

   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 TeX Live 2021.

3. 3.
   ​

   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.

4. 4.
   ​

   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.

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.

BookML is also available as a Docker image, which automatically compile all .tex files at the top of the /source folder containing the string \documentclass (even if commented out!). The image is identical to the one used for Overleaf, and so it contains a full copy of TeX Live 2021.

You can run the Docker image by opening a terminal in the folder containing the .tex files and running

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

Additional arguments are passed to make, for instance

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

will show an output similar to the one described in Getting started on your device.