The command-line interface¶

Jupyter Book comes with a command-line interface that makes it easy to build your books and run a few common functions. This page contains information about what you can do with the CLI.

This page is a complete reference for the CLI. For newcomers who would like to get started with the Jupyter Book CLI, we recommend starting with Overview and installation.

Note

You may also use a short-hand for jupyter-book in the command-line interface: jb. For example: jupyter-book build mybook/` is equivalent to ``jb build mybook/

See below for the full command-line reference

jupyter-book¶

Build and manage books with Jupyter.

jupyter-book [OPTIONS] COMMAND [ARGS]...

Options

--version¶: Show the version and exit.

build¶

Convert your book’s content to HTML or a PDF.

jupyter-book build [OPTIONS] PATH_BOOK

Options

--path-output <path_output>¶: Path to the output artifacts

--config <config>¶: Path to the YAML configuration file

--toc <toc>¶: Path to the Table of Contents YAML file

-W, --warningiserror¶: Error on warnings.

--builder <builder>¶

Which builder to use.

Options: html|pdfhtml|latex|pdflatex

Arguments

PATH_BOOK¶: Required argument

clean¶

Empty the _build directory except jupyter_cache. If the all option has been flagged, it will remove the entire _build. If html/latex option is flagged, it will remove the html/latex subdirectories.

jupyter-book clean [OPTIONS] PATH_BOOK

Options

-a, --all¶: Remove build directory.

--html¶: Remove html directory.

--latex¶: Remove latex directory.

Arguments

PATH_BOOK¶: Required argument

create¶

Create a simple Jupyter Book that you can customize.

jupyter-book create [OPTIONS] PATH_BOOK

Arguments

PATH_BOOK¶: Required argument

myst¶

Manipulate MyST markdown files.

jupyter-book myst [OPTIONS] COMMAND [ARGS]...

init¶

Add Jupytext metadata for your markdown file(s), with optional Kernel name.

jupyter-book myst init [OPTIONS] [PATH]...

Options

--kernel <kernel>¶: The name of the Jupyter kernel to attach to this markdown file.

Arguments

PATH¶: Optional argument(s)

page¶

Convert a single content file to HTML or PDF.

jupyter-book page [OPTIONS] PATH_PAGE

Options

--path-output <path_output>¶: Path to the output artifacts

--config <config>¶: Path to the YAML configuration file

--execute, --no-execute¶: Whether to execute the notebook. Default is –execute

Arguments

PATH_PAGE¶: Required argument

toc¶

Generate a _toc.yml file for your content folder. It also generates a _toc.yml file for sub-directories. The alpha-numeric name of valid content files will be used to choose the order of pages/sections. If any file is called “index.{extension}”, it will be chosen as the first file. Note that each folder must have at least one content file in it.

jupyter-book toc [OPTIONS] PATH

Options

--filename_split_char <filename_split_char>¶: A character used to split file names for titles

--skip_text <skip_text>¶: If this text is found in any files or folders, they will be skipped.

--output-folder <output_folder>¶: A folder where the TOC will be written. Default is path

--add-titles¶: Whether to generate page titles from file names.

Arguments

PATH¶: Required argument