Create books automatically

Create books automatically#

This section covers how you can create books automatically in order to get started more quickly.

Create a book from a simple template#

Jupyter Book lets you quickly generate a book structure from templates. This section covers the process of creating a template book and building it as an alternative to manually creating the files in your book.

To see your options for creating books from templates, run the following command:

jupyter-book create --help

Usage: jupyter-book create [OPTIONS] PATH_BOOK

  Create a Jupyter Book template that you can customize.

Options:
  --cookiecutter  Use cookiecutter to interactively create a Jupyter Book
                  template.
  --no-input      If using cookiecutter, do not prompt the user for input.
  -h, --help      Show this message and exit.

This option is best if you are starting from scratch, or would like to see one example of a simple Jupyter Book on your own filesystem.

If you’d just like to quickly create a sample book, you may do so by running the following command:

jupyter-book create mynewbook/

This will generate a mini Jupyter Book that you can both build and explore locally. It will have a few decisions made for you, and you can explore the configuration of the book in _config.yml and its structure in _toc.yml. Use this book as inspiration, or as a starting point to work from.

Create a more complete book from interactive prompts#

This option is best if you’d like to answer a few questions from the command line in order to create a template book that is more complex and customized for your use-case.

Jupyter Book also provides a Jupyter Book cookiecutter that can be used to interactively create a book directory structure.

The cookiecutter is suitable for users that want to create a ready-to-go repository to host their book that includes pre-populated metafiles such as README, LICENSE, CONDUCT, CONTRIBUTING, etc., as well as GitHub Actions workflow files to Publish to GitHub Pages.

To try the cookiecutter template, run the following command:

jupyter-book create mynewbook/ --cookiecutter

For more help, see the Jupyter Book cookiecutter GitHub repository, or run:

Create book files from a Table of Contents#

It is possible to use a _toc.yml file in order to create the skeleton of a book automatically. This is useful if you wish to quickly generate empty files from a single structure, and then populate them with content yourselves.

To create your book’s files from the Table of Contents, use the following command:

jupyter-book toc to-project path/to/_toc.yml

This will generate a collection of files according to the structure in _toc.yml.

In addition, you have a few options to control the behavior of this tool. See below for reference.

Usage: jupyter-book toc to-project [OPTIONS] TOC_FILE

  Create a project directory from a ToC file.

Options:
  -p, --path DIRECTORY      The root directory [default: ToC file directory].
  -e, --extension [rst|md]  The default file extension to use.  [default: rst]
  -o, --overwrite           Overwrite existing files.
  -h, --help                Show this message and exit.
Contents