Publish your book online

Publish your book online#

Once you’ve built the HTML for your book, you can host it online. The best way to do this is with a service that hosts static websites (because that’s what you have just created with Jupyter Book). In this tutorial, we’ll cover how to publish your book online with GitHub Pages, a popular and free online hosting platform.

Prerequisites#

Create an online repository for your book#

In order to connect your hosted book with your book’s source content, you should put your book’s source content in a public repository. This section describes one approach to create your own GitHub repository and add your book’s content to it.

  1. First, log in to GitHub, running the MCP server:

    • To run the github mcp server, in the .vscode/mcp.json file:

  2. Next, open Copilot and enter this in the prompt:

    Create a new repository called <Enter-repo-name>
- Include a readme file

    • Replace <Enter-repo-name> with your desired repository name (e.g., my-jupyter-book).

    • Copilot will create the repository for you and provide a link.

  3. Then, clone your new repository to your local machine:

    • In Copilot, enter the following prompt:

    clone [repository URL]

    • Replace [repository URL] with the link to your new repository (e.g., https://github.com/your-username/my-jupyter-book.git).

    • Copilot will clone the repository into your workspace, making it ready for you to add your book’s files.

  4. Copy all the files and folders from your textbook project into the newly cloned repository:

    • For example, if you created your book locally with jupyter-book create mylocalbook and your new repository is called myonlinebook, copy the contents of the mylocalbook folder into the myonlinebook folder.

    • You can do this using your file manager or with a terminal command like:

    cp -r mylocalbook/* myonlinebook/

    • Make sure to include all files and subfolders so your book builds correctly online.

  5. Finally, push your changes to GitHub:

    • In Copilot, enter the following command:

    commit and push all changes with the message "Your commit message here"

    Or, more specifically:

    git add .
git commit -m "Initial commit with book files"
git push origin main

    • This will upload your book’s files to your GitHub repository, making them available online.

Publish your book online with GitHub Pages#

We have just pushed the source files for our book into our GitHub repository. This makes it publicly accessible for you or others to see.

Next, we’ll publish the build artifact of our book online, so that it is rendered as a website.

The easiest way to use GitHub Pages with your built HTML is to use the ghp-import package. ghp-import is a lightweight Python package that makes it easy to push HTML content to a GitHub repository.

ghp-import works by copying all of the contents of your built book (i.e., the _build/html folder) to a branch of your repository called gh-pages, and pushes it to GitHub. The gh-pages branch will be created and populated automatically for you by ghp-import. To use ghp-import to host your book online with GitHub Pages, follow the steps below:

Note

Before performing the below steps, ensure that HTML has been built for each page of your book. There should be a collection of HTML files in your book’s _build/html folder.

You can also run the slash command /build_textbook and the agent will build the book for you automatically.

You can use simple prompts to let the agent handle the manual steps for you:

Publish my Jupyter Book to GitHub Pages
Deploy the built HTML to the gh-pages branch
Run the steps to make my book available online

When you enter one of these prompts, the agent will automatically:

  • Install the required ghp-import tool if needed

  • Deploy your built HTML to the gh-pages branch

  • Guide you to check your GitHub Pages settings if needed

This means you do not need to run each command manually—the agent will perform the steps for you and let you know when your book is live!

Note

You can also use the slash command /publish_textbook to publish your Jupyter Book to GitHub Pages. This command will trigger the agent to handle all deployment steps for you automatically.

If you prefer to do the steps manually, follow these instructions:

  1. Install ghp-import

    pip install ghp-import

  2. Update the settings for your GitHub Pages site:

    a. Use the gh-pages branch to host your website.

    b. Choose root directory / if you’re building the book in its own repository. Choose /docs directory if you’re building documentation with jupyter-book.

  3. From the main branch of your book’s root directory (which should contain the _build/html folder), call ghp-import and point it to your HTML files:

    ghp-import -n -p -f _build/html

Warning

Make sure that you included the -n - this tells GitHub not to build your book with Jekyll, which we don’t want because our HTML is already built! If you do not do this you may see 404 not found for your deployed content.

After a few minutes, your site should be viewable online at a URL such as: https://<your-github-username>.github.io/<your-repo-name>/. If not, check your repository settings under Options → GitHub Pages to ensure that the gh-pages branch is configured as the build source for GitHub Pages and/or to find the URL address GitHub is building for you.

To update your online book, make changes to your book’s content on the main branch of your repository, re-build your book with jupyter-book build mybookname/, and then use ghp-import -n -p -f _build/html as before to push the newly built HTML to the gh-pages branch.

Warning

Note this warning from the ghp-import GitHub repository:

“…ghp-import will DESTROY your gh-pages branch… and assumes that the gh-pages branch is 100% derivative. You should never edit files in your gh-pages branch by hand if you’re using this script…”

Contents