# Configuration reference#

You can configure Jupyter Book with a YAML configuration file (_config.yml). This file controls a number of options and feature flags.

This page is a reference for the _config.yml structure along with default values for each option. For information about using and configuring specific features, see the Topic Guides.

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.

## 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                   : "2022"  # 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 artifacts. 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_enable_extensions:  # default extensions to enable in the myst parser. See https://myst-parser.readthedocs.io/en/latest/using/syntax-optional.html
# - amsmath
- colon_fence
# - deflist
- dollarmath
# - html_image
# - replacements
# - smartquotes
- substitution
myst_url_schemes: [mailto, http, https] # URI schemes that will be recognised as external URLs in Markdown links
myst_dmath_double_inline: true  # Allow display math () within an inline context

#######################################################################################
# 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
use_multitoc_numbering    : true   # Continuous numbering across parts/chapters
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
announcement              : "" # A banner announcement at the top of the site.

#######################################################################################
# LaTeX-specific settings
latex:
latex_engine              : pdflatex  # one of 'pdflatex', 'xelatex' (recommended for unicode), 'luatex', 'platex', 'uplatex'
use_jupyterbook_latex     : true # use sphinx-jupyterbook-latex for pdf builds as default

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

#######################################################################################