Skip to article frontmatterSkip to article content

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

  1. Go to this repository

  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 topmenu, 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 GHpages from the template.

  1. Use the book link (code →\rightarrow below About) to your Github page where the book is hosted.

  2. The output resembles Figure 3.

Once the book has been deploy, you can visit your site which looks like this.

Figure 3:Once the book has been deploy, you can visit your site which looks like this.

Repo folder structure

Your GitHub repository looks like the one shown in Figure 4. We have the following subfolders:

Once the book has been deploy, you can visit your site which looks like this.

Figure 4:Once the book has been deploy, you can visit your site which looks like this.

Make and deploy changes

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

Using the GitHub IDE
Using your favourite editor
Entirely locally 🌶

It is possible to work directly in the GitHub environment: no need to install anything as this is already covered with the GH actions that we created.

  1. Click on the index.md file in the Content folder

  2. Click on the drop down icon next to the pencil icon and choose open in github.dev This will start the GitHub development environment where you can edit the files directly in your browser.

  3. Edit the file by replacing the names with your own and commit your changes, see Figure 5

Figure 5:Working directly in the GitHub development environment.

Now, if you go back to your repository and click on actions 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 live!

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). We included a GitHb action that automatically creates a pdf export of your book using Typst when you push changes to your repository. You can also create the pdf locally if you have the Typst CLI installed. We cover the pdf export later in more detail

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