Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Updated: 03 nov 2025

The instructions on this page guide you through the process of:

Create a repository

Follow these instruction to use the GitHub template repository to create your own book for this workshop:

  1. Go to the repository for this book

  2. Click the green button use this template and click create a new repository.

  3. Choose a proper name of your repository (this will be also part of your URL!) and choose the option public.

  4. In your repository, click on settings and in the left menu on Pages and choose Github Actions

Figure 1:Follow these steps to create your own repository from the template.

  1. Click on code and click on the gear-icon (near About) at the right site of the page.

  2. Check the box Use your GitHub Pages website.

  3. Go to Actions in the top menu, click on the (red) initial commit and click re-run all jobs

The book will now be deployed again - where now it can actually load GitHub pages.

Figure 2:Follow these steps to create your own GH Pages site from the template.

View your book online

The previous stps set up your repository with GitHub Pages, which a GitHub Actions workflow to automatically build your book (a website) and deploy it online. The URL of your book is based on your GitHub username:

https://USERNAME.github.io/workshop-template

This is, in fact, how the website for this document is created:
https://jupyter-book.github.io/workshop-template/

You can also find the link easily from you GitHub repository home page under the “About” section on the right-hand side (illustrated in Figure 4).

The home page of your new book website should look like Figure 3.

The home page of your new site, which you can visit once the GitHub Action workflow has successfully completed.

Figure 3:The home page of your new site, which you can visit once the GitHub Action workflow has successfully completed.

Repo folder structure

Your GitHub repository may look similar to the one shown in Figure 4; note the following directories:

Illustration of repository folder structure.

Figure 4:Illustration of repository folder structure.

As proceed through the workshop you will edit the files in your new repository.

Edit the book

You have a number of options for making changes to the book’s source and seeing how they affect the output.

Locally
Online

  1. Clone the repository to your local machine using Git.

git clone git@github.com:<github_user_name>/workshop-template.git

  1. Install Jupyter Book, using the virtual environment manager of your choice (all of the tools used today can easily be handled using pip)

pip install -r requirements.txt

  1. Make a change to one of the files in the content directory using a text editor.

  2. (optional) Commit the the change using Git and push it to the remote repository (this will trigger the GitHub Actions workflow and rebuild the website, which can be viewed at the same URL described above). If you go back to your repository and click on the Actions tab you will see that the workflow is running to build and deploy your book. After a few minutes, you can refresh your book page and see your changes!

  3. Build the book from source and serve it locally.

jupyter book start

  1. Preview the book in your browser at http://localhost:3000

Create a PDF export

A clear advantage of JB2 over JB1 is the ability to easily create a high quality PDF export of your book (as well as other formats). In a later lesson of this workshop, we will build a PDF locally and/or modify the GitHb Action workflow to automatically create a PDF export of your book using Typst when changes are pushed changes to your repository.

Jupyter Book 2 Workshop Template
Create your first Jupyter Book 2
Jupyter Book 2 Workshop Template
Jupyter Book Fundamentals