GitHub workflow: publish your book online to GitHub Pages

We developed a workflow which builds your TeachBook in your repository for all branches and publishes them online via GitHub Pages. In simplified terms, it builds the website based on your repository.

The TeachBooks Template 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.

The workflow has the following features:

• Publishing of your TeachBook-repository (built with Jupyter Book) to GitHub Pages
• Ability to publish both private (GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server required) and public (GitHub Free is enough) repositories.
  GitHub Teams is free for teachers as described in the GitHub documentation.
  If you have an organization for your TeachBook on GitHub, link your GitHub team rights to your organization as described on the GitHub website.
• Publishing all or a selection of branches, allowing to build a draft version of the TeachBook online which reduces the need for local builds of the book
• Provides a summary describing where the TeachBook is published, errors in the build process per branch and how the publish step is configured
• Caching of already built books so that it can be partially 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 settings 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 copies one of the branches to root.
• Adds an 'archived'-banner to old branches / branches of previous years.

How to start using this workflow

As previously mentioned, 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 TeachBook 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 least 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 TeachBook 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 the workflow: TeachBook 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 (just a space) whenever it's not defined in the repository variables.
  • This defines an alias (custom URL) for a branch
  • Variables should be a space-separated list of branch names, e.g. 'alias:really-long-branch-name`
  • If no alias is wanted, BRANCH_ALIASES may be set to (just a 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 (just a 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 triggers the workflow. You can limit the branches or subdirectories.

View the workflow progress and summary

Whenever the workflow is triggered, its 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/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)