A cookiecutter template for creating a simple Jupyter Book. See the rendered version of this cookiecutter template here.
An example template created by this cookiecutter is shown below:
my_book
├── .github
│ └── workflows
│ └── deploy.yml
├── CONDUCT.md
├── CONTRIBUTING.md
├── LICENSE
├── my_book
│ ├── _config.yml
│ ├── _toc.yml
│ ├── content.md
│ ├── intro.md
│ ├── logo.png
│ ├── markdown.md
│ ├── notebooks.ipynb
│ └── references.bib
├── README.md
└── requirements.txt
- Install Cookiecutter if you haven't installed it yet:
$ pip install -U cookiecutter
- Use
cookiecutter-jupyter-book
to generate a Jupyter Book template and fill out the requested information (default templating values are shown in square brackets[]
and will be used if no other information is entered):
$ cookiecutter git@github.com:executablebooks/cookiecutter-jupyter-book.git
author_name [Captain Jupyter]: Tomas Beuzen
github_or_gitlab_username [tomasbeuzen]:
book_name [My Book]:
book_slug [my_book]:
book_short_description [This cookiecutter creates a simple boilerplate for a Jupyter Book.]: My first Jupyter Book!
version ['0.1.0']:
Select open_source_license:
1 - MIT license
2 - BSD license
3 - ISC license
4 - Apache Software License 2.0
5 - GNU General Public License v3
6 - None
Choose from 1, 2, 3, 4, 5, 6 [1]:
Select include_ci_files:
1 - github
2 - gitlab
3 - no
Choose from 1, 2, 3 [1]:
- Install the Jupyter Book package requirements from the
requirements.txt
file (it is recommended to do this in a virtual environment, e.g., using conda):
# Optional steps to create and activate virtual environment
$ conda create --name mybook python=3.8 -y
$ conda activate mybook
$ cd my_book
$ pip install -r requirements.txt
- Build the HTML render of your Jupyter Book:
$ jupyter-book build my_book/
-
View your rendered book in
my_book/_build/html/index.html
. -
Make edits to your book by adding more content, updating the table of contents in
my_book/_toc.yml
, and and/or by editing the configuration filemy_book/_config.yml
. See the Jupyter Book documentation for more information on customizing your book. -
cookiecutter-jupyter-book
optionally comes with CI workflow files to help easily deploy your book online. A CI workflow file would have been included in your directory structure if you chose1 - github
or2 - gitlab
forSelect include_ci_files:
in Step 2 above. For example, if you chose1 - github
, when ready to deploy your book online:-
Make sure your book builds locally as expected (
jupyter-book build my_book/
) and that you have updated therequirements.txt
file to include any additional packages required to build your book; -
Create a new public GitHub repository to host your book;
-
Push your local book (including the
.github
hidden directory) to your GitHub repository. There are many ways to do this, for example:$ git init $ git add . $ git commit -m "first commit" $ git remote add origin git@github.com:<user>/<repository-name>.git $ git push -u origin main
-
The GitHub Actions workflow provided with the cookiecutter (
my_book/.github/workflows/deploy.yml
) will automatically deploy your book to thegh-pages
branch of your repository once pushed. It is typically available after a few minutes athttps://<user>.github.io/<myonlinebook>/
. You may need to go to theSettings
tab of your repository and under the GitHub Pages heading, choose thegh-pages branch
from the Source drop-down list. For alternative methods of deploying your book online, see the See the Jupyter Book documentation.
Note: by default, the GitHub Actions workflow file included with this cookiecutter builds the book with Ubuntu and Python 3.8. You can modify the OS/Python version for the build in the
.github/workflows/deploy.yml
file on lines 15 and 16 respectively.Read more about GitHub Pages and Jupyter Book here, or using GitLab Pages here.
-
We welcome and recognize all contributions. If you'd like to contribute to the project by providing feedback, identifying a bug or working on a new feature, check out the contributing guide to get started.
You can see a list of current contributors in the contributors tab.
This template was inspired and made possible by the Cookiecutter project and the Jupyter Book project.