Cookiecutter Jupyter Book
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
cookiecutter-jupyter-bookto 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 email@example.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 : Select include_ci_files: 1 - github 2 - gitlab 3 - no Choose from 1, 2, 3 :
- Install the Jupyter Book package requirements from the
requirements.txtfile (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
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 file
my_book/_config.yml. See the Jupyter Book documentation for more information on customizing your book.
cookiecutter-jupyter-bookoptionally 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 chose
1 - githubor
2 - gitlabfor
Select include_ci_files:in Step 2 above. For example, if you chose
1 - 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 the
requirements.txtfile 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
.githubhidden 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 firstname.lastname@example.org:<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 the
gh-pagesbranch of your repository once pushed. It is typically available after a few minutes at
https://<user>.github.io/<myonlinebook>/. You may need to go to the
Settingstab of your repository and under the GitHub Pages heading, choose the
gh-pages branchfrom 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.ymlfile on lines 15 and 16 respectively.
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.