On this page

Configure book settings

In Jupyter Book, most configuration is controlled with a Configuration YAML file (_config.yml). This file controls a number of options that you may use to configure your book.

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 more detail for specific features.

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 behavior of the book. In this case:

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

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

  • logo: controls 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 with 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 throughout this book’s documentation for different ways that you can configure your book.

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 are 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 suggest an edit or open an issue. In each case, they require the following configuration to exist:

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

Configuration reference

For a reference example of all the possible Binder links and their default values, see the section below:

#######################################################################################
# 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
exclude_patterns            : []  # Patterns to skip when building the book. Can be glob-style (e.g. "*skip.ipynb")

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

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

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

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.
  config                    :   # key-value pairs to directly over-ride the Sphinx configuration
Publish with Netlify Table of Contents structure