Skip to content

Latest commit

 

History

History
66 lines (45 loc) · 2.53 KB

build.md

File metadata and controls

66 lines (45 loc) · 2.53 KB
Raw

Build your book

(clean-build)=

Clean your book's generated files

It is possible to "clean up" the files that you generate when you build your book. This is often useful if you have recently changed a lot of content in order to ensure that you build your book from a clean slate.

You can clean up your book's generated content by running the following command:

jupyter-book clean mybookname/

By default, this will delete all folders inside mybookname/_build except for a folder called .jupyter_cache. This ensures that the content of your book will be regenerated, while the cache that is generated by running your book's code will not be deleted (because regenerating it may take some time).

To delete the .jupyter_cache folder as well, add the --all flag like so:

jupyter-book clean mybookname/ --all

This will entirely remove the folders in the _build/ directory.

(config:exclude-non-toc-files)=

Disable building files that aren't specified in the TOC

By default, Jupyter Book will build all files that are in your book's folder, regardless of whether they are specified in the Table of Contents. To disable this behavior and only build files that are specified in the TOC, use the following pattern in _config.yml:

only_build_toc_files: true

Note that files that are in hidden folders (e.g. in .github or .venv) will still be built even if they are not specified in the TOC. You should exclude these files explicitly.

Debug your book's build process

When debugging your book build, the following options can be helpful:

jupyter-book build -W -n --keep-going mybookname/

This will check for missing references (-n), turning them into errors (-W), but will still attempt to run the full build (--keep-going), so that you can see all errors in one run.

You can also use -v or -vvv to increase verbosity.

A list of book output types

You can build a variety of outputs using Jupyter Book. To choose a different builder, use the --builder <builder-name> configuration when running jupyter-book build from the command-line. Here is a list of builders that are available to you:

  • html: HTML outputs (default)
  • singlehtml: A single HTML page for your book
  • dirhtml: HTML outputs with <filename>/index.html structure.
  • pdfhtml: Build a PDF via HTML outputs (see )
  • linkcheck: Run the Sphinx link checker (see )
  • latex: Build Latex files for your book
  • pdflatex: Build a PDF of your book via Latex (see )