3. Build your book#
Once you’ve added content and configured your book, it’s time to build outputs for your book. We’ll use the jupyter-book build
command line tool for this.
Currently, there are two kinds of supported outputs: a HTML website for your book, and a PDF that contains all the pages of your book that is built from the book HTML. In this tutorial, we’ll focus on building HTML outputs. See Build a PDF to find more on building a PDF.
3.1. Prerequisites#
In order to build the HTML for each page, you should have followed the steps in Overview and Create your book. You should have a collection of notebook/Markdown files in your <book-path>
folder, a _toc.yml
file that defines the structure of your book, and any configuration you’d like in the _config.yml
file.
Note
The TU Delft template has all the necessary configurations and files. You have to adjust the content and the _toc.yml
files to your individual work. Follow the instruction at the Anatomy of a Jupyter Book for further information about all the files of your book.
3.2. Create environment#
In order to build your books, you have to create a closed environment for the necessary packages to be downloaded. There are several ways to achieve that. For the purpose of this tutorial, we will use a Conda environment.
Note
You can create more than one environment with different names. However, the inplementation of TU Delft follows one specific requirement.txt
file and as a concequence environment
. Thus, it is not necessary to create multiple environments.
First, navigate your command line to the root path of the book. Then, you can create and activate an environment by running the following commands (preferably one by one):
conda create --name=<env-name> python=3.7
conda activate <env-name>
conda install pip
pip install -r requirements.txt
In principle, the previous command will create and activate the environment. If something goes wrong, check on the internet for the error messages, or (if you cannot find a solution) contact the responsible department of TU Delft.
Delete environment
If you want to remove an environment, run the following command:
conda remove --name <env-name> --all
3.3. Active environment#
Every time you want to build your book again, make sure you have the right environment activated by running the following command:
conda activate env-name
Deactivate environment
If you want to deactivate an environment, run the following command:
conda deactivate <env-name>
3.4. Build your book’s HTML#
Now that your book’s content is in your book folder, you’ve defined your book’s structure in _toc.yml
, and you have built the right environment, you can build the HTML for your book.
Do so by running the following command:
jupyter-book build <book-path>
This will generate a fully-functioning HTML site using a static site generator. The site will be placed in the _build/html
folder, something like this:
book-path
└──_build
└── html
├── _images
├── _static
├── index.html
├── intro.html
...
These are the static files for a standalone website! They contain the HTML and all assets needed to view your book in a browser.
You can open the pages in the site by navigating to that folder and opening the html
files with your web browser.
Note
You can also use the short-hand jb
for jupyter-book
. E.g.,: jb build <book-path>
.
3.5. Page Cacheing#
By default, Jupyter Book will only build the HTML for pages that have been updated since the last time you built the book.
If you’d like to force Jupyter Book to re-build a particular page, you can either edit the corresponding file in your book’s folder, or delete that page’s HTML in the _build/html
folder.
You can also signal a full re-build using the --all
option:
jupyter-book build --all <book-path>
3.6. Preview your built HTML#
To preview your book, you can open the generated HTML files in your browser. Either double-click the html file in your local folder, or enter the absolute path to the file in your browser navigation bar adding file://
at the beginning (e.g. file://<book-path>/_build/index.html
).
Take a look at the web page that was generated from the markdown page that you created. Note how the links you inserted were automatically resolved to point to the right place. This is how you can keep consistent pointers from one section of your book to another.
3.7. More Information#
Find more information about building your book: