Compile with BookML

GitHub action for compiling LaTeX files to HTML using BookML.

Basic usage

Add the file .github/workflows/bookml.yaml to your GitHub repository 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

On every push, the action will checkout the repository, compile all .tex files containing the string \documentclass, then create a GitHub release containing all the outputs generated by BookML. The permissions key is necessary to create GitHub releases.

What's new

• v1.2.7 Minor changes: links to files in the workflow summary now open in a new tab, ensuring they scroll to the line that generated the message (if known), and references to /auxdir/ link to the aux-directory artifact.

• v1.2.6 Major changes: capture and report multiline TeX error messages, and clarify that the outputs are also in the aux directory.

• v1.2.5 Minor change: improve header of summary and release notes.

• v1.2.4 Major change: much improved readability of error messages, with working links to the cause of the error when using the BookML Docker image v0.21.0 or later.

• v1.2.3. Major change: replace output messages in release with link to equivalent GitHub page.

• v1.2.2. Bugfix: truncate messages correctly to stay below 125000 character limit.

• v1.2.1. Bugfix: respect value of inputs.checkout.

• v1.2. Several improvements in user experience.

  • The release text includes direct links to each download and a link to the workflow run page on GitHub.
  • Error messages are highlighted in red in the workflow run page and are included prominently in the release text.
  • The workflow summary includes an abridged version of the release text.
  • Breaking change: custom values of AUX_DIR are ignored. This action sets its own value of AUX_DIR in order to compile the files in a temporary folder outside of the workspace.
  • Breaking change: the aux directory is now uploaded as job artifact rather than being attached to the release. This is essentially equivalent to the previous behaviour, except that artifacts normally expire after 90 days.

Options

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

For example, the following will use the BookML v0.19.3 Docker image, replace the bookml/ folder with version v0.19.3, use the TeX Live scheme small, and set a longer timeout.

- name: Compile with BookML
  uses: vlmantova/bookml-action@v1
  with:
    scheme: small
    version: v0.19.3
    replace-bookml: true
    timeout-minutes: 15

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