This intermediate-level how-to will have you creating a static course website based on the Jupyter Book project. The official documentation has more details about the platform, but this documentation should get you up and started quickly for teaching. The site will be hosted using free hosting from GitHub Pages. These directions are suitable for a full semester-long course with a syllabus. If you're running a simple workshop with 3 sessions or fewer, check out "How to" Create a lesson for a Workshop.

Here are a few example teaching websites created with Jupyter Book:

Fork the Template Repository

In this first step, we will create a GitHub account and make a copy of the existing template. This process is known as "forking" a repository. Finally, we'll create a free website hosted by GitHub Pages.

Create a GitHub Account

Click "Sign up" and supply a username, email address, and password for your account.

github sign up page

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".

fork button in github

Rename your repository

In the repository, click on "Settings" and rename the repository to your course name. Then click "Rename".

Settings menu and repository rename form

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.)

The GitHub Pages settings form

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."

the enable workflows button

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.

the box showing no workflows have run

Installing Software on your Local Machine

You have successfully created an account on GitHub, forked our template, and created a website. Now you're ready to start modifying the website to meet your needs for teaching. You can think of GitHub as the place where you will store the latest version of your site. Each time you make an improvement to your site, you will "save" a version to GitHub. Not only will GitHub save your latest changes, but it will keep a copy of every revision you make!

In order to make changes to your site, you will download your files to your local machine. On your own machine, you can make changes and test them out before "saving" them back to GitHub and updating your website to make the changes "live." To edit your site on your local machine, you will need some software:

  • git- command line software for uploading and downloading your files from GitHub
  • Python- the Python progamming language we will use for writing code
  • The Jupyter Notebook- a local version that runs on your machine to view and edit your notebooks and other files
  • Jupyter Book- command line software to convert your notebooks and markdown files into HTML website files

Let's install each of these.
Note: The order of these installations does matter. Some of these installation methods will not work if you run them out of order.

Apple OS X Installations

Note!

If you have an older installation of Python (such as Python 2.7), you may run into issues with symbolic links. See fixing symbolic links.

Skip to Windows installation Instructions ->

Install git (Apple Mac OS X)

  1. Open terminal Terminal is included in Mac OS X by default Press command (⌘) and spacebar to launch spotlight search. (Alternatively, you can launch spotlight by clicking the magnifying glass in the upper righthand corner of OS X.) Type in "terminal" and hit enter. (You can also launch terminal by navigating to your Applications folder.)

  2. Check if Brew is installed Type or copy and paste the following code into your terminal, then press return.

    brew --version
    

    If you receive a brew version, then it is already installed on your machine. You may skip the next step.

  3. Install Brew if not installed First we install xcode, copy and paste the following code into your terminal, then press return.

    xcode-select --install
    

    This will install Xcode on your machine.
    To install Brew, copy and paste the following into your terminal, then press return.

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    

    Note!
    If you have trouble getting xcode to install, you can download it directly from the Apple Developer Tools Site. You will need to create an Apple Developer account.

  4. Install git Type (or copy and paste) the following code into your terminal, then press return.

    brew install git
    
  5. Confirm successful installation Type (or copy and paste) the following code into your terminal then press return.

    git --version
    

    You should receive a version number in return such as:

    git version 2.92.2
    

Note!
You may also install git without using the command line by installing from a binary.

Install Python (Apple Mac OS X)

  1. Install Python from terminal Assuming you have Brew installed, type (or copy and paste) the following code into your terminal.
    brew install python3
    
    Then press return. Your installation should now start.
  2. Confirm successful installation Type (or copy and paste) the following code into your terminal.
    python --version
    
    Then press return. You should receive a version number in return such as:
    python version 3.9
    

Note!
You may also install Python without using the command line by installing from a binary. Only install Python 3; Python 2 is no longer being used.

Install The Jupyter Notebook (Apple Mac OS X)

  1. Check if "pip" is installed When you installed Python, it should have also installed "pip." You can check to see if you have pip by typing:
    pip --version
    
    in the terminal and pressing return. You should receive a version number in return such as:
    pip 20.1.1 from /opt/anaconda3/lib/python3.8/site-packages/pip (python 3.8)
    
    If you do not receive confirmation, you can also try:
    pip3 --version
    
  2. Install Jupyter Notebook type the following into your terminal.
    pip install notebook
    
    Then press return. Your installation should now start.
  3. Confirm successful installation type:
    jupyter-notebook --version
    
    Then press return. You should receive a version number in return such as:
    6.0.3
    

Install Jupyter Book (Apple Mac OS X)

  1. Check if "pip" is installed When you installed Python, it should have also installed "pip." You can check to see if you have pip by typing:
    pip --version
    
    in the terminal and pressing return. You should receive a version number in return such as:
    pip 20.1.1 from /opt/anaconda3/lib/python3.8/site-packages/pip (python 3.8)
    
    If you do not receive confirmation, you can also try: pip3 --version.
  2. Install Jupyter Book type the following into your terminal.
    pip install jupyter-book
    
    Then press return. Your installation should now start.
  3. Confirm successful installation type:
    jupyter-book --version
    
    Then press return. You should receive a version number in return such as:
    Jupyter Book: 0.10.0
    MyST-NB: 0.11.1
    Sphinx Book Theme: 0.0.39
    MyST-Parser: 0.13.3
    Jupyter-Cache: 0.4.2
    NbClient: 0.5.1
    

Congratulations, you've installed all the necessary software for Apple Mac OS X!

Microsoft Windows 10 Installations

Note!

Order Matters

The order of these installations matters! Earlier installations are used in order to complete later installations.

Administrator Access Required

If you are using a laptop supplied by your institution, make sure you have administrative privileges to install software.

  1. Open "Control Panel".
  2. Navigate to User Accounts.
  3. Examine your user account and make sure it says "Administrator" under your account.

The place where administrators are listed

If your account is not an administrator, you will need to contact your IT department in order to get administrative privileges for installing the necessary software.

PATH Issues

If you have successfully installed an application but it is not recognized in Git Bash, you may have a path issue. See fixing PATH issues.

Install git (Microsoft Windows 10)

  1. Download Git Go to the git website. Download the "64-bit Git for Windows Setup".
  2. Install Git For each setting, choose the default. You may, optionally, wish to change the default editor from Vim (an advanced text editor) to something simpler like Notepad. This is not necessary for our purposes but it may be easier for you if the command line is intimidating.
  3. Confirm successful installation Click on the Windows icon in the lower left corner. Type the following:
    git bash
    
    Then press "Enter." This will launch Git Bash, allowing you to use git.
  4. Confirm successful installation Type (or copy and paste) the following code into Git Bash.
    git --version
    
    Then press return. You should receive a version number in return such as:
    git version 2.31.1.windows.1
    
Note!

Git Bash vs. Command Prompt

The order of these installations matters! Earlier installations are used in order to complete later installations.

For these directions, we assume you are using Git Bash rather than the Windows Command Prompt. It is possible to use Git with the Windows Command Prompt, but some of the commands will be different. To check which one you are using, look in the upper lefthand corner of the window.

Git Bash will say "MINGW64" in the upper lefthand corner of the window.

Command Prompt will say "Command Prompt".

Git Bash vs. Command Prompt

Install Python (Microsoft Windows 10)

Warning!
Jupyter Book has an incompatibility with Python 3.8. We will use Python 3.7 for better compatibility.

  1. Download Python 3.7.9 from the Python website. At the bottom of the page, choose "Windows x86-64 executable installer".

  2. Start the installation by double-clicking on the executable file.

    Warning!
    Make sure to select "Add Python 3.7 to PATH" before choosing "Install Now."

    The "Add Python 3.7 to path" prompt

  3. Confirm successful installation
    If you have a Git Bash window already open, close it and then open a new one.
    Type:

    python --version
    

    then press Enter. You should receive a response like:

    Python 3.7.9
    

Install The Jupyter Notebook (Microsoft Windows 10)

  1. Check if "pip" is installed When you installed Python, it should have also installed "pip." You can check to see if you have pip by typing:
    pip --version
    
    in Git Bash and pressing Enter. You should receive a version number in return such as:
    pip 20.1.1 from c:\users\username\appdata\local\programs\python\python37\lib\site-packages\pip (python 3.7)
    
    If you do not receive confirmation, you can also try:
    pip3 --version
    
  2. Install Jupyter Notebook type the following into your terminal.
    pip install notebook
    
    Then press return. Your installation should now start.
  3. Confirm successful installation type:
    jupyter-notebook --version
    
    Then press return. You should receive a version number in return such as:
    6.3.0
    

Install Jupyter Book (Microsoft Windows 10)

Warning!
Jupyter Book has compatibility issues with Python 3.8. Please make sure you have installed Python 3.7.

  1. Check if "pip" is installed When you installed Python, it should have also installed "pip." You can check to see if you have pip by typing:
    pip --version
    
    in Git Bash and pressing Enter. You should receive a version number in return such as:
    pip 20.1.1 from c:\users\username\appdata\local\programs\python\python37\lib\site-packages\pip (python 3.7)
    
    If you do not receive confirmation, you can also try:
    pip3 --version
    
  2. Install Jupyter Book type the following into your terminal.
    pip install jupyter-book
    
    Then press Enter. Your installation should now start.
  3. Confirm successful installation type:
    jupyter-book --version
    
    Then press Enter. You should receive a version number in return such as:
    Jupyter Book: 0.10.2
    MyST-NB: 0.12.3
    Sphinx Book Theme: 0.1.0
    MyST-Parser: 0.13.7
    Jupyter-Cache: 0.4.2
    NbClient: 0.5.3
    

Congratulations, you've installed all the necessary software for Microsoft Windows 10!

Clone your repository to your local machine

Now that we have all of our software installed, we will configure git on our local machine to interact with GitHub. Our first goal is to download the materials in your GitHub repository to your local machine.

When we have the files on our local machine, we can then make changes using an editor of our choice. We recommend using The Jupyter Notebook to edit .ipynb files, so you can see exactly how they will look online.

Note!
There are a variety of other editors that will open and edit *.ipynb* files, from the most basic tools like *TextEdit* (OS X) or *Notepad* (Windows 10) to advanced, fully-featured Integrated Development Environments (IDEs) such as *Visual Studio* and *PyCharm*. For our purposes, simple editors will be enough but you may eventually want to investigate other options that have many helpful features.

Both the terminal (Apple OS X) and Git Bash (Microsoft Windows 10) use unix for navigating and working with local folders and files. We will use some basic commands to move around in your local folders and files.

Note!
Our goal is mainly to be able to navigate the file system, not to do any advanced tasks with Unix commands. If you would like to learn more unix commands, we recommend:

We will learn three unix commands for navigating folders:

Unix command English meaning purpose
pwd Present Working Directory outputs your current location on your computer file system
ls list outputs the files and directories in your current location
ls -a list all the addition of the -a flag includes output of hidden files and directories which begin with a period
cd folderName/ change directory moves the user down into the folderName directory
cd .. change directory moves the user up one directory
cd ~ change directory move to user's home directory

Note!
On *Apple OS X*, the user's home directory is `/Users/UserName`. On *Microsoft Windows 10*, the user's home directory is usually `/c/Users/UserName`

Open either terminal and Git Bash to try out each of these commands. Explore your file system for practice. Finally, navigate to the directory where you would like to make a copy of your website on your local machine.

Note!
When you are navigating to a particular file or directory using `cd`, you usually do not need to type out the whole name. Simply type out a few letters then press *tab*. If there is a single match in the current directory, the full name will be completed automatically! If the name is not auto-completed, press tab twice to show all matching results for the letters typed so far. You can then type a few more letters to make your selection clear before tabbing one more time to automatically complete the name.

Setting up git on your local machine

We will use the following git commands to set up git. We will only use them a single time. They are important for setup, but you will not use them again unless you set up git on another machine or need to re-install git.

git setup commands English meaning purpose
git config --global user.name "Judith Cohen" Configure the global git user with this name Sets the user name in git. Only needs to be run once.
git config --global user.email "username@gmail.com" Configure the global git user with this email address Sets the user email for git. Use the same email address as your GitHub account. Only needs to be run once.

Cloning your repository

The clone command helps us copy a repository from GitHub to our local machine. First, however, we need to grab an address from GitHub to clone our repository. Open your web browser and log into GitHub. Click on your repository. Then click on the large, green "Code" button. Finally click on the clipboard to copy the "HTTPS" address.
the clone address
The address will look like

https://github.com/yourGitHubUserName/yourRepoName.git

Return to your terminal or Git Bash. Use the pwd command to confirm you are in the directory where you would like to make a local copy of your repository. If everything looks good, run git clone followed by the address you copied. It should look something like:

git clone https://github.com/yourGitHubUserName/yourRepoName.git

Note!
The familiar shortcut for paste in Windows (Ctrl + V) does not work in Git Bash. To paste in Git Bash, you can use the keyboard key "Insert" or right-click then select "paste".

Congratulations! You've copied your repository to your local machine. Now let's learn how to make changes.

Make local changes

Now that you have a local copy of your site, you can make changes and improve it. You can use two different kinds of editors to make improvements. For improvements to the website configuration, you can use a simple text editor. For improvements to the lessons, we will use The Jupyter Notebook.

Making improvements to the website configuration

The full documentation for Jupyter Book contains many more details, but we will focus on two main files:

  • config.yml- The general site configuration file which gives us lots of options for how the site will look and function.
  • toc.yml- The file that configures the Table of Contents for our website.

Both of these files are simple text files, so you do not need the command line to change them. You can simply open them with a plain text editor like TextEdit (Apple OS X) or Notepad (Microsoft Windows 10).

Note!

If you would like to try a more advanced editor, you might check out PyCharm or Visual Studio. Both have free versions that work on Apple OS X and Microsoft Windows 10.

Editing config.yml

Each setting in the config.yml file has description in form of a comment, but we also recommend taking a look at the Jupyter Book Documentation page. The basic settings are fairly easy to change, but there's also a tremendous amount of flexibility for more powerful transformations. Here are a few basic items you're likely to want to change:

Setting Use
title The title of the book. Will be placed in the left navbar.
author The author of the book
logo The path to a logo for your book
repository: url The github URL to your book's repository
Warning!

If you don't change the repository URL, your notebook lessons will not launch correctly. Your repository URL will look like:

https://github.com/yourGitHubUserName/yourRepositoryName

Editing toc.yml

This file edits the table of contents found in the lefthand navigation of the site. We recommend taking a look at the Jupyter Book documentation for the table of contents. You have an option for organizing your table of contents:

  • Chapters
  • Chapters broken up into parts

The original site table of contents is composed of chapters broken up into parts. Here are a few things to note when making changes:

  • The Jupyter Book builder is exacting about spacing for the table of contents file. It is essential to have the correct number of tabs for your file names and chapters.
  • When you specify the location of a chapter file, you do not need to add the file extension, such as .md or .ipynb
  • We recommend making only one significant change to your table of contents at a time. If the build fails, it will be easy to change back to a working version.

Making Changes to the Website Content

The main content of your site is composed of two kinds of files:

  • Jupyter Notebook Files (.ipynb)- These are notebook files that we can view and change with Jupyter Notebook.
  • Markdown Files (.md)- These are simple text files with a little markdown for styling and adding things like links, images, and other explanatory content. They can be edited in The Jupyter Notebook, a simple text editor, or a more advanced editor. The advantage of The Jupyter Notebook or a more advanced editor is that either will give you a preview of your Markdown.

Editing with The Jupyter Notebook

The Jupyter Notebook is launched from the command line. Open your command line, either Git Bash or Terminal, and navigate to the repository using the cd command. When you are in your repository, run:

jupyter notebook

This will launch The Jupyter Notebook in your browser. You will then be able to open any notebook (.ipynb) or markdown (.md) files to edit. Your command line, either Git Bash or Terminal, will be running a local server for Jupyter Notebook, so do not quit the command line or The Jupyter Notebook will also stop. Simply minimize the window out of the way.

As you modify each notebook or markdown file, you will need to save changes. On OS X, use (⌘ + s). On Windows 10, use (Ctrl + s). When you're finished making changes, save, close The Jupyter Notebook tab, then close the command line.

Note!

If you are working on a Jupyter Notebook, we recommend clearing all code outputs before saving. That will essentially reset the notebook for the next user. If you do not clear the outputs, any existing outputs will be visible for the next user. This can be confusing!

clearing all outputs

Previewing your website changes

If you would like to preview what your website will look like, you need to use Jupyter Book to build the site first. Essentially, this takes all the information from your configuration file, your table of contents file, your markdown files, and your notebook files to create a website. We are converting all of content files into HTML files.

Open your command line, navigate to your repository, then run the Jupyter Book build command:

jupyter-book build .
Note!

The period here specifies to build the book in the present working directory. If you were in a different directly, you could specify the location of the repository instead of using a period.

Assuming there are no errors and your book builds successfully, the HTML files will be deposited in _build/html. To preview your website you can open the file main index through your file explorer by navigating to _build/html/index.html. Alternatively, you could copy the file location link that posts at the end of the successful build and paste it into a web browser.

preview of successful output

Note!

As you make changes, you may need to build your website many times to see previews. Rather than retyping the jupyter-book build . command, you can simply press the ↑ (up) key. Git Bash or Terminal will cycle back through the most recent commands you entered. (This is also very helpful if you typed a very long command that was just off by one letter.) It may even make sense to have a sense to one terminal window open just for building. Possibly another may be open running The Jupyter Notebook. Terminal, on OS X, has support for tabbed windows.

When you are happy with your website changes, you can push them to GitHub to make them live on your site.

Push Changes to the Web

Now that you have made changes to your site, the final step is to make those changes live on the web. In the language of git, we need to push our changes to our GitHub repository. Here, we assume that you are working alone on the site, so we are not going to go into issues that may be significant for working collaboratively with git. (For example, these directions discuss pushing to GitHub, but do not discuss pulling, merging, or other more advanced methods. If you would like to learn more about git, a great starting point is Corey Schafer's YouTube Series on git.)

The three essential git commands

When it comes to pushing your repository to GitHub, we will use three commands:

git command purpose
git add -A Add all the files in the repository
git commit -m "A message describing your commit" Attach this message to my updates
git push Push my changes to GitHub
  1. Open up your command line, either Git Bash or terminal, then navigate to your repository using cd.
  2. Use the git add -A command to add all the files in the repository. If you would prefer to just add one file, you can specify that file instead of using the -A flag.
  3. Use the git commit -m "Put a commit message here" command to commit a message to your changes. The text in quotation marks should describe the changes you made for this update. Git keeps track of all of your changes, so if you ever need to roll back changes this message will be very useful for finding which version of your repository you want to return to.
  4. Use the git push command to push to your GitHub repository. When you push for the first time, you will need to validate your identity as the owner of your GitHub account by entering your password. It is important here that the git global user email you set also matches your GitHub account email. If git prompts you to "Sign in with your browser", choose that option, as it may set permissions so that future logins are not necessary. Alternatively, you can send a personal access token as your password which should keep you from having to enter your password every time you push.
    The GitHub sign-in
Note!
After your push completes successfully, it may take 2-3 minutes before the live version of your site is updated. The change is not immediate.

What if I mess up local installation?

It happens to everyone at some point. If your local install is completely broken, you can simply delete the local repository folder from your computer. Simply use the git clone command again to download a new copy from GitHub. The downloaded copy will contain any changes from your last push.

What if I need to go back a version?

We don't recommend doing this if you're collaborating with others. If you're the only person pushing to the repository though, you can use the git revert command to undo your last push. You will need the seven-digit "hash" of your last commit which can be found on the GitHub website.

the most recent commit hash

If you click on the clock which shows the number of commits, it will show the hashes for all recent commits.

all recent commit hashes in github

Grab the hash for the commit you would like to revert and run:

git revert 1234567