# Configure book settings¶

In Jupyter Book, most configurations are controlled in a YAML configuration file (_config.yml). This file controls a number of options that you may use to configure your book (the defaults can be found at the bottom of this page).

This page describes the general structure of _config.yml and how you can use it to control some basic parts of your book. The rest of the pages in this section describe specific features in more detail.

## Structure of _config.yml¶

Here is a very simple _config.yml configuration (it is taken from the demo book config file):

# Book settings
title: My sample book
author: The Jupyter Book Community
logo: 'images/logo.png'


As you can see, keys correspond to configuration options and their values are how you control the behaviour of the book. In this case:

• title: sets the title of your book. In the HTML output, it is displayed in the left sidebar.

• author: sets the book’s author. In the HTML output, it is displayed in the footer.

• logo: sets the logo of the book, relative to the book root. In the HTML output, it is displayed above the title in the left sidebar.

There are also some configuration options that are nested. For example, to configure your book to include Binder links in any section built from a Jupyter notebook, you may use the following configuration:

# Information about where the book exists on the web
repository:

# Configure your Binder links, such as the URL of the BinderHub.
launch_buttons:
binderhub_url             : https://mybinder.org


Look out for different book configuration options throughout this book’s documentation.

Caution

YAML can be tricky when it comes to how it treats certain kinds of values. For example, when using strings in YAML it is usually fine to omit quotes around them. However, there are certain values that will be converted to boolean values if they do not have strings around them. For example, false, true, off, etc. In addition, pure numbers will be converted to float or int unless you put strings around them.

There is a collection of buttons that you can use to link back to your source repository. This lets users browse the repository or take actions like suggesting an edit or opening an issue. In each case, they require the following configuration to be set:

repository:
url: https://github.com/{your-book-url}


### Add a button to open issues¶

To add a button to open an issue about the current page, use the following configuration:

repository:
url: https://github.com/{your-book-url}
html:
use_issues_button: true


### Add a button to suggest edits¶

You can add a button to each page that will allow users to edit the page text directly and submit a pull request to update the documentation. To include this button, use the following configuration:

repository:
url: https://github.com/{your-book-url}
path_to_book: path/to/your/book  # An optional path to your book, defaults to repo root
branch: yourbranch  # An optional branch, defaults to master
html:
use_edit_page_button: true


### 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.

Users who are familiar with Sphinx configuration may wish to directly add extensions or set options to parse to the underlying Sphinx application.

sphinx:
extra_extensions: [my_extension]


This will append to the list of extensions already loaded by Jupyter Book.

To add a local extension that requires a path, use:

sphinx:
local_extensions:
<name>: <path>


This will **append to the list of extensions already loaded by Jupyter Book and update the sys.path so the local extension can be found.

### Specifying Sphinx Configuration Values¶

sphinx:
config:
my_option: my_value


Warning

Any options set in this section will override default configurations set by Jupyter Book. Use at your own risk!

If you wish to inspect a conf.py representation of the generated configuration, which Jupyter Book will pass to Sphinx, from the command line run:

jb config sphinx mybookname/


The advanced section on Sphinx configuration.

## Configuration defaults¶

Below is the full default configuration file. Anything you set in your own _config.yml will be merged into these defaults before they are used to configure the build.

#######################################################################################
# A default configuration that will be loaded for all jupyter books
# Users are expected to override these values in their own _config.yml file.
# This is also the "master list" of all allowed keys and values.

#######################################################################################
# Book settings
title                       : My Jupyter Book  # The title of the book. Will be placed in the left navbar.
author                      : The Jupyter Book community  # The author of the book
copyright                   : "2020"  # Copyright year to be placed in the footer
logo                        : ""  # A path to the book logo
# Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb")
exclude_patterns            : [_build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints"]
# Auto-exclude files not in the toc
only_build_toc_files        : false

#######################################################################################
# Execution settings
execute:
execute_notebooks         : auto  # Whether to execute notebooks at build time. Must be one of ("auto", "force", "cache", "off")
cache                     : ""    # A path to the jupyter cache that will be used to store execution artifacs. Defaults to _build/.jupyter_cache/
exclude_patterns          : []    # A list of patterns to *skip* in execution (e.g. a notebook that takes a really long time)
timeout                   : 30    # The maximum time (in seconds) each notebook cell is allowed to run.
run_in_temp               : false # If True, then a temporary directory will be created and used as the command working directory (cwd),
# otherwise the notebook's parent directory will be the cwd.
allow_errors              : false # If False, when a code cell raises an error the execution is stopped, otherwise all cells are always run.
stderr_output             : show  # One of 'show', 'remove', 'remove-warn', 'warn', 'error', 'severe'

#######################################################################################
# Parse and render settings
parse:
myst_extended_syntax      : false  # enable MyST extended syntax support (see documents for details)
myst_url_schemes          : [mailto, http, https]  # URI schemes that will be recognised as external URLs in Markdown links

#######################################################################################
# HTML-specific settings
html:
favicon                   : ""  # A path to a favicon image
use_edit_page_button      : false  # Whether to add an "edit this page" button to pages. If true, repository information in repository: must be filled in
use_issues_button         : false  # Whether to add an "open an issue" button
extra_navbar              : Powered by <a href="https://jupyterbook.org">Jupyter Book</a>  # Will be displayed underneath the left navbar.
extra_footer              : ""  # Will be displayed underneath the footer.
google_analytics_id       : ""  # A GA id that can be used to track book views.
baseurl                   : ""  # The base URL where your book will be hosted. Used for creating image previews and social links. e.g.: https://mypage.com/mybook/
hypothesis              : false
utterances              : false

#######################################################################################
# LaTeX-specific settings
latex:
latex_engine              : pdflatex  # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'

#######################################################################################
# Launch button settings
launch_buttons:
notebook_interface        : classic  # The interface interactive links will activate ["classic", "jupyterlab"]
binderhub_url             : https://mybinder.org  # The URL of the BinderHub (e.g., https://mybinder.org)
jupyterhub_url            : ""  # The URL of the JupyterHub (e.g., https://datahub.berkeley.edu)
thebe                     : false  # Add a thebe button to pages (requires the repository to run on Binder)