Skip to content

How to Auto-Refresh with Baseprinter

This guide shows how to automatically rerun Baseprinter and reload HTML previews of Baseprint document snapshots in your web browser whenever you save changes to a source text file.

Prerequisites

You will need either:

OR install

Alternatives

This guide uses live-server and nodemon, but there are many alternatives with similar functionality (e.g., entr).

How it works

You can use any text editor to save changes to your source files. In an independent terminal window, run a script that watches your source files for changes. When this script starts live-server, a preview page URL will be printed to be opened in your web browser. This script will automatically rerun baseprinter to generate a new Baseprint snapshot and HTML preview. When the HTML files are updated, the browser window will automatically reload the preview page. Press CTRL-C to stop the script.

Warning

Some editors, like vim on Linux, by default change files in a way that prevents the proper functioning of file monitoring. Either monitor a folder or, in the case of vim, use set backupcopy=yes.

Steps

1. Add a baseprint-fast recipe

In a justfile located in your source directory, add a baseprint-fast recipe that skips PDF generation.

baseprint-fast:
  baseprinter --defaults pandocin.yaml --baseprint baseprint --outdir _preview --skip-pdf

Generating the PDF is slower, and it won't automatically reload in the browser.

Alternatively, you can use an equivalent bash script or Makefile if you prefer. If you do, make sure the nodemon --exec option in the next step reflects your preference.

2. Add a live-baseprint script

In the source directory, add a live-baseprint script with the following contents and run chmod +x live-baseprint on the new file.

#!/usr/bin/env bash
mkdir -p _preview
live-server --no-css-inject _preview &
nodemon --exec 'just baseprint-fast' --ext md,yaml,bib
true

3. Add a contained-live-baseprint script (Optional)

This step is only recommended if you are running Baseprinter in a container. Otherwise, just run ./live-baseprint.

In the source directory, add a contained-live-baseprint script with the following contents and run chmod +x contained-live-baseprint on the new file.

#!/usr/bin/env bash
SRCDIR=$(realpath $(dirname "$0"))
podman run \
    --rm -v=$SRCDIR:/mnt -w=/mnt -it --init -p=8080:8080 \
    registry.gitlab.com/perm.pub/dock/baseprinter \
    ./live-baseprint

4. Run live-baseprint and edit a source file

Run either ./contained-live-baseprint or ./live-baseprint, depending on whether you are running Baseprinter in a container or not.

Note the message

Serving "_preview" at http://127.0.0.1:8080

that is printed out. Open your web browser to that URL.

Edit a source file and notice that the preview in your browser is automatically reloaded.

If you want to manually trigger an update, type rs (and press enter).

5. Stop auto-refresh

Hit CTRL-C to stop the live-baseprint script.

Running in a container

Warning

When running contained-live-baseprint, Baseprinter inside the container will not have access to any paths outside the source working directory.