Since your content is already on GitHub, you can easily host it as a `github-pages`
Once your content is on GitHub, you can easily host it as a [GitHub Pages](https://docs.github.com/en/github/working-with-github-pages) website. This is a service where GitHub hosts your static files as if they were a standalone website.
website. This is a service where GitHub hosts your static files as if they were
a standalone website.
There are two ways to quickly host your book with GitHub Pages:
There are two ways you can quickly host your book with GitHub Pages:
***Manually push your book's HTML** to a branch that is hosted
*Push your book's HTML to a branch that is hosted
by GitHub Pages.
by GitHub Pages.
***Use a GitHub Action to automatically build your book**
* Use a GitHub Action to automatically build your book
and update your website when you change the content.
and update your website when you change the content.
## Manually host your book with GitHub Pages
## Push your book to a branch hosted by GitHub Pages
The easiest way to use GitHub-pages with your built HTML is to use the
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.
tool. It is a lightweight Python package that makes it easier to push HTML content
`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:
to a GitHub repository.
```{note}
```{note}
Ensure that your the HTML has been built for each page of your book
Before performing the below steps, ensure that HTML has been built for each page of your book
(see {doc}`the previous section <../start/build>`). There should be a collection of HTML
(see {doc}`the previous section <../start/build>`). There should be a collection of HTML
files in your book's `_build/html` folder.
files in your book's `_build/html` folder.
```
```
Follow these steps to use `ghp-import`:
1. Install `ghp-import`
1. Install `ghp-import`
```
```
pip install ghp-import
pip install ghp-import
```
```
2.Call `ghp-import` and point it to your HTML files, like so:
2.From the `master` branch of your book's root directory (which should contain the `_build/html` folder) call `ghp-import` and point it to your HTML files, like so:
```
```
ghp-import -n -p -f mylocalbook/_build/html
ghp-import -n -p -f mylocalbook/_build/html
```
```
This will cause `ghp-import` to push *all* of the contents of the `_build/html` folder
to the `gh-pages` branch of your current repository, and push the contents to GitHub.
By default, this generally means your site should now be viewable online.
```{warning}
```{warning}
Make sure that you included the `-n` - this tells GitHub *not* to build your book with
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!
[Jekyll](https://jekyllrb.com/), which we don't want because our HTML is already built!
```
Typically after a few minutes your site should be viewable online at a url such as: `https://<user>.github.io/<myonlinebook>/`. 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, you would simply make changes to your book's content on the `master` branch of your repository, re-build your book with `jupyter-book build mybookname/`, and then use `ghp-import -n -p -f mylocalbook/_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...*"
```
```
## Automatically host your book with GitHub Actions
## Automatically host your book with GitHub Actions
GitHub Actions is a tool that allows you to automate things
[GitHub Actions](https://docs.github.com/en/actions) is a tool that allows you to automate things on GitHub. It is used for a variety of things, such as testing, publishing packages, and continuous integration.
on GitHub. It is used for a variety of things, such as testing,
publishing packages, and continuous integration.
```{note}
```{note}
You should be familiar with GitHub Actions before using them
You should be familiar with GitHub Actions before using them
Once you've built the HTML for your book, it's time to host it 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**
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).
(because that's what you have just created with Jupyter Book). There are many options for doing this, and these sections cover some of the
There are many options for doing this, and these sections cover some of the
more popular ones.
more popular ones.
(publish/online-repo)=
(publish/online-repo)=
## Create an *online* repository for your book
## Create an online repository for your book
Regardless of the approach you use for publishing your book online, it will require
Regardless of the approach you use for publishing your book online, it will require
you to host your book's content in a GitHub repository.
you to host your book's content in an online repository such as GitHub. This section describes one approach you can use to create your own GitHub repository and add your book's content to it.
This section covers the steps to create your own GitHub repository,
and to add your book's content to it.
1. First, log-in to GitHub, then go to the "create a new repository" page:
1. First, log-in to GitHub, then go to the "create a new repository" page:<https://github.com/new>
<https://github.com/new>
2. Next, give your online repository a name and a description. Make your repository public and do not initialize with a README file, then click "Create repository".
2. Next, add a name and description for your book. You can choose whatever
3. Now, clone the (currently empty) online repository to a location on your local computer. You can do this via the command line with:
initialization you'd like.
3. Now, clone the empty repository to your computer:
4. Copy all of your book files and folders (what was created when you ran `jupyter-book build mybook`)
4. Copy all of your book files and folders into this newly cloned repository. For example, if you created your book locally with `jupyter-book create mylocalbook` and your new repository is called `myonlinebook`, you could do this via the command line with:
into the new repository. For example, if you created your book locally with `jupyter-book create mylocalbook`
and your online repository is called `myonlinebook`, the command would be:
```bash
```bash
cp-r mylocalbook/_build/html/* myonlinebook/
cp-r mylocalbook/* myonlinebook/
```
```
This will copy over the local book files into the online book folder.
5. Now you need to sync your local and remote (i.e., online) repositories. You can do this with the following commands:
5. Commit the new files to the repository in `myonlinebook/`:
```bash
```bash
cd myonlinebook
cd myonlinebook
...
@@ -48,5 +36,5 @@ and to add your book's content to it.
...
@@ -48,5 +36,5 @@ and to add your book's content to it.
git push
git push
```
```
Follow the steps in the next sections for how to host your book online with various
Follow the steps in the next sections to learn how to host your book online with various
