Skip to content

How to Run Baseprinter via GitHub

Baseprinter can be run in a GitHub Actions workflow. Baseprinter generates a snapshot of your document in Baseprint Document Format (BpDF) and an HTML/PDF preview with GitHub Pages.

Objective

You will create a minimal GitHub repository that will automatically run Baseprinter whenever source files are updated.

Alternatives

Instead of this how-to guide, you can alternatively follow the tutorial to author via GitHub, which demonstrates using an example LaTeX file as source.

Prerequisites

  • A GitHub account

Steps

1. Create a repository

First, create a new repository from a repository template. This new repository will contain:

  • a GitHub Actions workflow file that automatically generates Baseprint snapshots and previews, and
  • a trivial pandocin.yaml Pandoc defaults file.

These files will be copied from this Baseprinter repository template. The workflow file is located at .github/workflows/baseprinter.yaml.

Create repository from the template

2. Enable GitHub Pages

Follow these substeps to publish to GitHub Pages:

  • On GitHub, navigate to your site's repository.
  • Under your repository name, click Settings (it might be a tab or in a dropdown menu).
  • In the Code and automation section of the sidebar, click Pages.
  • Under Build and deployment, under Source, select GitHub Actions.

3. Show the Preview URL

  • Click on the Code tab of the repository.
  • Click the gear icon to the right of About.
  • Under the Website field, check Use your GitHub Pages website.
  • Click the Save changes button.

4. Check the Status of the Preview Job (Optional)

  • Click the Actions tab.
  • Click on the workflow in progress: "Deploy Baseprint preview to GitHub Pages".
  • Wait for the workflow to complete successfully.
  • Click on the link https://<username>.github.io/<reponame>/ under the "deploy" job.

5. Edit your source files

  • Edit the metadata in pandocin.yaml.
  • Edit the document text in doc.md.

You can edit these files directly on GitHub, or use git or compatible software to edit the files locally, commit them, and then push them to GitHub.

After the source files are updated on GitHub, a new workflow run should start to update the preview website.

Conclusion

You now have a preview of your Baseprint document snapshot available at https://<username>.github.io/<reponame>/. This preview will be automatically updated whenever there are changes to the repository.

The Baseprint document snapshot has been saved in the autobaseprint branch as a directory (git tree) named baseprint.

Questions or Feedback

If you have any questions or feedback, feel free to contact Castedo.