GitHub workflow to publish online to GitHub Pages

We developed a workflow which builds the Jupyter Books in your repository for all branches, and publishes them online via GitHub Pages.

It has the following features:

• Publishing of your Jupyter Book-repository to GitHub Pages
• Publishes both private (GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server required) and public (GitHub Free is enough) repositories.
• Publishing all or a selection of branches, allowing to build draft version of the book online preventing local builds
• A summary describing where the book is published, errors in the build process per branch and how the publish step is configured
• Caching of build books so that it can be reused when another branch is published or the next build contains critical errors
• Caching of python environment to speed up the workflow
• Allowing to use submodules within your book
• Customizable trigger for the workflow itself
• Optionally preprocess branches using the teachbooks package.
• Converting branch-names to well-defined URLs
• Customizable settings on where the books should be deployed including alias for branch-names and selection of one branch to be deployed on root. The workflow will gives warnings if these setting are ill-defined or conflicting. Although aliases are not allowed by GitHub Pages, it seems you can use one alias, but not more.
• Redirects the root directory to one of the branches or copy one of the branches to root.
• Adds an 'archived'-banner to old branches / branches of previous years.

The TeachBooks template book uses this functionality for example: The workflow call-deploy-book.yml calls the deploy-book.yml workflow, which builds the Jupyter books at the calling repository for all branches, and deploys them via GitHub Pages.

How to start using this workflow

This workflow is used in TeachBooks/template. Feel free to use it for your TeachBook as well:

1. Add teachbooks to your requirements.txt file in your root folder
2. Move all the book files (including _config.yml and _toc.yml) to a subdirectory book/.
3. Copy the call-deploy-book.yml workflow to the /.github/workflows folder in your repository.
4. Set source for GitHub pages to GitHub Actions under Settings - Pages - Build and deployment - Source - GitHub Actions (as long as you don't do this the workflow deploys all branches which build successfully).
5. (only required for private repositories) create a Personal Access Token (classic) with at lesat the scopes repo, read:org and gist as described in the github documentation, and add this token with the name GH_PAT as a Repository secret or Organization secret ( Settings > Secrets and variables > Actions > Repository secrets or Organization secrets.)
6. Trigger the workflow by making an edit to the book by editing and committing changes to one of the files in the book/ subdirectory (available under Code) or manually activating the workflow under Actions - All workflows - call-deploy-book - Run workflow - Use workflow from branch: <the branch you did step 1, 2 and 3 in> - Run workflow (this workflow).
7. Now checkout the progress and summary of the publishing workflow under Actions - All workflows - call-deploy-book -<the most recent workflow run>.

Customize book publishing settings

You can adapt the behaviour by setting repository variables as explained here or using the VS Code Extension GitHub Actions. Define the following repository variables:

• PRIMARY_BRANCH which is set to main whenever it's not defined in the repository variables.
  • This sets the branch or alias (when using 'redirect' for BEHAVIOR_PRIMARY) which is shown on root.
  • It is advised to show your most recent branch on root.
• BEHAVIOR_PRIMARY which is set to redirect whenever it's not defined in the repository variables.
  • This indicates whether to copy the PRIMARY_BRANCH to root ('copy') or redirect from root to the PRIMARY_BRANCH ('redirect')
  • Advised to use 'redirect' if you expect to archive a version in the future so that the URL doesn't change for the reader.
• BRANCH_ALIASES which is set to (space) whenever it's not defined in the repository variables.
  • This defines an alias (custom URL) for a branch
  • Variable should be an Space-separated list of branch names, e.g. 'alias:really-long-branch-name`
  • If no alias is wanted, BRANCH_ALIASES may be set to ' ' (space).
• BRANCHES_TO_DEPLOY which is set to * (all branches) whenever it's not defined in the repository variables.
  • This defines the branches to deploy.
  • It should be a space-separated list of branch names, e.g. 'main second third'.
• BRANCHES_TO_PREPROCESS which is to to (space, no branch) whenever it's not defined in the repository variables
  • This defines the branches to preprocess with the TeachBooks package, which removed book-pages and config lines defined with # START REMOVE FROM PUBLISH and # END REMOVE FROM PUBLISH
  • It should be a space-separated list of branch names, e.g. 'main second third'.
  • If no preprocessing is required, BRANCH_TO_PREPROCESS may be set to ' ' (space).
• BRANCHES_ARCHIVED which is set to (space, no branch) whenever it's not defined in the repository variables
  • This adds a banner to the published branch: You are viewing an archived version of the book. Click here for the latest version.
  • It should be a space-separate list of branch names, e.g. 'main second third'.

In call-deploy-book.yml itself you can specify the trigger for this workflow. By default, a push to any branch trigger the workflow. You can limit the branches or subdirectories.

Workflow progress and summary

Whenever the workflow is triggered, progress and a summary can be seen under the Actions- All workflows - call-deploy-book in GitHub. It shows you a descriptive summary:

• Ill-defined repository configuration variables (in Annotations)
• Which branches are published and where (https://<username/organization_name>.github.io/<repository_name> (case sensitive)) including which branch is published on the website root and the applied alias
• Errors in the build process
• How the repository variables are defined during the build.

Here's an example for a summary for the template book:

Branches deployed

Branch 🎋	Link 🔗	Build status ☑️
main	https://teachbooks.github.io/template/main	✅ Published
version2	https://teachbooks.github.io/template/version2	🔴 Build failed [1]
version3	https://teachbooks.github.io/template/version3	⭕ Build failed [2]

Legend for build status

✅ Published - build success, new version published.

🔴 Build failed [1] - build failure, previous version of the book reused.

⭕ Build failed [2] - build failure, no previous version reused.

Primary book at root

The book at the website root https://teachbooks.github.io/testable-template/ redirects to the primary branch main (status: ✅ Published).

Aliases

Alias ➡️	Target 🎯	Link 🔗	Build status ☑️
draft	main	https://teachbooks.github.io/template/draft	✅ Published

Preview of build errors & warnings

For more details please see the corresponding build-books jobs in the left pane.

On branch version2:

�[91m/home/runner/work/template/template/book/some_content/overview.md:5: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]�[39;49;00m

On branch version3:

/home/runner/work/_temp/ff8c8325-8d8b-4c0b-a2b2-32d2169c55bc.sh: line 8: teachbooks: command not found

Repository configuration variables

Variables can be set at https://github.com/TeachBooks/template/settings/variables/actions

PRIMARY_BRANCH=main (default value used)
BRANCH_ALIASES=draft:main
BRANCHES_TO_DEPLOY=* (default value used)
BRANCHES_TO_PREPROCESS=main
BEHAVIOR_PRIMARY=redirect (default value used)
BRANCHES_ARCHIVED= (default value used)