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:
  url                       : https://github.com/yourusername/yourbookrepo

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

Add source repository buttons

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

Advanced configuration (with sphinx)

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

To add extensions, use:

sphinx:
  extra_extensions: [my_extension]

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

To set additional Sphinx configurations:

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/

See also

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"]

#######################################################################################
# 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_repository_button     : false  # Whether to add a link to your repository button
  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.
  home_page_in_navbar       : true  # Whether to include your home page in the left Navigation Bar
  baseurl                   : ""  # The base URL where your book will be hosted. Used for creating image previews and social links. e.g.: https://mypage.com/mybook/
  comments:
    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)
  colab_url                 : "" # The URL of Google Colab (https://colab.research.google.com)

repository:
  url                       : https://github.com/executablebooks/jupyter-book  # The URL to your book's repository
  path_to_book              : ""  # A path to your book's folder, relative to the repository root.
  branch                    : master  # Which branch of the repository should be used when creating links

#######################################################################################
# Advanced and power-user settings
sphinx:
  extra_extensions          :   # A list of extra extensions to load by Sphinx (added to those already used by JB).
  config                    :   # key-value pairs to directly over-ride the Sphinx configuration