Publishing your book with GitHub Pages

GitHub pages is a free service that GitHub provides to let you host website contentusing your GitHub repositories.

Once you've built the intermediate files for your book (in _build) or built the HTMLfor your book (in _site), you can push your book contents to GitHub so thatothers can access your book.

Prerequisites

  • If you are building your book's HTML manually

We assume that you have already built your book's HTML and thatyour HTML content is in the _site/ folder. We also assume that you have aGitHub repository created for your book.

  • If you are using GitHub-page's Jekyll builder

We assume that you have aGitHub repository created for your book.We also assume that your book's template and content have been pushed toyour GitHub repository.

Publish your book's HTML manually to GitHub-pages

You can manually publish HTML to GitHub-pages so that it will serve a websitefor you. To do so, we'll need to push the HTML for our book to a branch, tell GitHub-pagesthat this branch contains raw HTML (not a Jekyll template), and then activateGitHub-pages on the repository. To do this, follow these steps:

  • Confirm that your book's HTML is built. You should see acollection of HTML files/folders in the _site folder.
  • Install the ghp-import tool. This is a command-line tool forquickly pushing some built HTML to a GitHub-pages branch.
  1. pip install ghp-import
  • Use ghp-import to push your book's HTML onto the gh-pages branch of your repository.
  1. ghp-import -n -p -f _site

The -n adds a .nojekyll file to your book's built HTML, and the -p and -f tellghp-import to push the contents of _site/ to the gh-pages branch. Run ghp-import -hto see more configuration options for this tool.

  • Confirm that your gh-pages branch has newly-pushed HTML for your book. You should seea .nojekyll file as well as the contents of _site/ in the root of your gh-pages branch.
  • Enable GitHub site building for your repository.

From your GitHub repository, click Settings then scroll down to theGitHub Pages section. You should see the message Your site is published at <YOUR-URL>.Ensure that you're building from the gh-pages branch.

  • Go to the URL listed at <YOUR-URL> and you should see your live site.

Automatically build your book's HTML with the GitHub Pages Jekyll builder

You'll need to activate GitHub-pages on your repository in order to tell GitHubto host a website from the repository's contents.To do so, follow these steps:

  • Confirm that each page's HTML is built. You should see acollection of HTML files/folders in the _build folder.
  • Commit and push the changes to your repository.
  • Enable GitHub site building for your repository.

From your GitHub repository, click Settings then scroll down to theGitHub Pages section. You should see the message Your site is published at <YOUR-URL>.Ensure that you're building from the correct folder.

  • Go to the URL listed at <YOUR-URL> and you should see your live site.

That should be all that is needed for GitHub Pages to automatically buildand publish your site. Any time you push changes to the _build/ folder(by running jupyter-book build locally and pushing the changes to GitHub),your book content will update.

This page was created by The Jupyter Book Community