Ctrl+K

Publish online with GitHub Pages

Publish online with GitHub Pages#

User types

This page is useful for user type 3, 4 and 5.

We developed a workflow which builds the Jupyter books in your repository for all branches, and publishes them online via GitHub Pages. The GitHub template book uses this functionality for example.

To use this feature, add the workflow call-deploy-book.yml to the /.github/workflows folder in your repository. Furthermore, set source for GitHub pages to GitHub Actions under Settings - Pages - Build and deployment - Source - GitHub Actions. Additional tip: set repository website as your GitHub Pages website under Code- About - - Website - Use your GitHub Pages Website

This workflow requires a requirements.txt file with teachbooks in your root folder, and all the book files (including _config.yml and _toc.yml) should be in a subdirectory book/.

You can adapt the behaviour by setting repository variables in GitHub as explained here. 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 which is hosted on root.

    • It is advised to make it published to start using draft-publish-workflow

  • BRANCH_ALIASES which is set to draft:main whenever it’s not defined in the repository variables.

    • This defines aliases for branches

    • It should be a space-separated list of alias-rules, e.g. ‘draft:main alias:really-long-branch-name`

    • It is advised to link book to publish.

    • If no aliases are 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’.-

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.

Whenever the workflow is triggered, progress can be seen under the Actions tab in GitHub. From this tab, you can also initiate it without any trigger commits.

When the workflow has finished, visit your build book at https://<username/organization_name>.github.io/<repository_name> (case sensitive). Eg. for the template book it is https://teachbooks.github.io/template.