# 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
- A [GitHub account](https://github.com/)
- [Visual Studio Code](https://code.visualstudio.com/) or another MCP-compatible editor
---
## 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:
:::raw html
:::
2. Next, open Copilot and enter this in the prompt:
```txt
Create a new repository called
- Include a readme file
```
- Replace `` 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:
```txt
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:
```zsh
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:
```zsh
commit and push all changes with the message "Your commit message here"
```
---
Or, more specifically:
```zsh
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`](https://github.com/davisp/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`**
```zsh
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:**
```zsh
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](https://jekyllrb.com/), 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://.github.io//`. 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](https://github.com/davisp/ghp-import):
"...*`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...*"
```