Contents
Creating your own Jupyter Book Website for Teaching¶
The official Jupyter Book documentation has more details about the platform. This tutorial is intended to help teachers get a course website up and running quickly for teaching. This tutorial will help you create a class website using free hosting from GitHub Pages. See the GitHub Pages documentation for details about using a custom domain and other possibilities.
Create a GitHub Account¶
Click “Sign up” and supply a username, email address, and password for your account.
Verify your email address with GitHub by clicking the “Verify Email Address” button sent to your email.
Fork the Constellate Notebooks repository¶
Visit the Constellate notebooks repository. In the upper right-hand corner click on “Fork”.
Rename your repository¶
In the repository, click on “Settings” and rename the repository to your course name. Then click “Rename”.
GitHub Pages Settings¶
Navigate back into “Settings” then choose “Pages” in the lefthand navigation. Check that the source is the branch “gh-pages” and the folder is “/(root)”. If necessary, click the “Save” button. (This is also where you can find settings for a custom domain if you own one you would like to use.)
If a link is listed, you should be able to click it to view your site immediately.
Approving GitHub Actions¶
Our last step is to approve automatic workflows called GitHub actions. These will automatically create a new version of your website every time you make a change. Click on the “Actions” tab, then click “I understand my workflows, go ahead and enable them.”
There are two workflows created by default:
Ensure Clean Notebook Metadata- Reminds users if they forget to clear all notebook cells. This workflow can be safely deleted if it is not useful to you.
deploy-book- This workflow automatically generates your website after you make a change. We recommend keeping it in place to make updating your website easy. This method is documented in the official Jupyter Book documentation.
When you first open this page, it will say “There are no workflow runs yet” since the workflows are triggered by making a change to your repository. After each subsequent change, you will be able to inspect a log of the workflows to see if they completed successfully.
