1 Set up Overleaf

Option 1: start from the Overleaf BookML template.

Option 2: add the .github/workflows/bookml.yaml file to your project as explained in the BookML manual.

In either case, follow the step-by-step instructions to link your Overleaf project with a GitHub repository.

Caveat: it will go wrong if your project has spaces in the name (what really matters is that the repository name is without spaces).


Exercises for after the project is linked:

Exercise 1.

Find the repository on GitHub.

Answer.

Open the GitHub syncing page on Overleaf and follow the link there.

Exercise 2.

Find where the action is running, and see it working in real time.

Answer.

Go to the GitHub repository. Right after a push/sync, you will see a small amber dot right above the list of files. Click on that. The dot becomes a green tick, or a red cross, once compilation is finished.

Exercise 3.

Did you receive an email at the end?

Answer.

If not, click on the ‘Watch’ icon and make sure that ‘All Activity’ is selected.

Exercise 4.

Speed up compilation by changing TeX Live scheme.

Answer.

Look at the bookml.yaml and replace ‘full’ with ‘small’, i.e.

with:
# scheme can be basic, small, medium, full
scheme: small
Exercise 5.

Find where the past releases and past action runs are.

Answer.

The releases appear on the front page of the repository under the ‘Releases’ heading (to the right on a desktop, to the bottom on mobile).

Exercise 6.

Deliberately introduce an error, for instance a non-existent macro, and push your changes to GitHub. What happens when you click on the links appearing in the error messages?

Answer.

The links should bring you to the line that generated the error (or at least where / thinks the error is).

Exercise 7.

Use a different version of BookML: either replace the bookml folder (but not GNUmakefile), or use the options version and replace-bookml in bookml.yaml. Use \BookMLversion to check which version is running. This file is compiled with version v0.28.5.

Answer.

The best way is to reupload the bookml folder from the release.zip file you find on GitHub. You must delete the bookml folder first.

Another option is to set

version: v0.27.0
replace-bookml: true

This instructs GitHub to use the Docker image v0.27.0, and replace the bookml folder with the version baked into the Docker image.

Just use

replace-bookml: true

to automatically use the latest version of BookML.