Configuration File#

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 TU Delft implementation uses and what has to be changed when creating a new 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.

Configuration defaults#

Below is the full default configuration file for the TU Delft implementation.

Note

The TU Delft template provides default settings for creating a new book, and it is advisable to only modify the necessary ones. These parameters are marked with an asterisk (*) in the following list and with the phrase Change this parameter in the _config.yml file for easy reference.

Book Settings#

All the basic information regarding the book.

#######################################################################################
# Book Settings
title: "\"How-To\" Manual"
author: Theodosios Athanasakis
description: Manual for all the professors that want to publish their books with Jupyter books implementation.
copyright: Delft University of Technology, CC BY-SA 4.0
logo: content/images/tudelft.png
exclude_patterns: [ _build, Thumbs.db, .DS_Store, "**.ipynb_checkpoints" ]
only_build_toc_files: true
title*

The title of the book. Will be placed in the left navbar.

author*

The author of the book.

description*

Text to indicate what the book is about.

copyright

Copyright tag to be placed in the footer.

logo

A path to the book logo.

exclude_patterns

Patterns to skip when building the book. Any files that match the patterns described there will be excluded from the build.

only_build_toc_files

Auto-exclude files not in the ToC and avoid building README, etc.

Execution Settings#

No need to change anything.

See also

See more information: Execute and cache your pages.

#######################################################################################
# Execution Settings
execute:
  execute_notebooks: force
  cache: ""
  exclude_patterns: [ ]
  timeout: 30
  run_in_temp: false
  allow_errors: false
  stderr_output: show
execute_notebooks

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

The maximum time (in seconds) each notebook cell is allowed to run.

run_in_temp

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

If False, when a code cell raises an error, the execution is stopped; otherwise all cells are always run.

stderr_output

One of ‘show’, ‘remove’, ‘remove-warn’, ‘warn’, ‘error’, ‘severe’.

Parse and Render Settings#

No need to change anything.

See also

See more information: Syntax Extensions.

#######################################################################################
# Parse and Render Settings
parse:
  myst_enable_extensions:
    - amsmath
    - colon_fence # To allow for ::: instead of ``` blocks.
    - deflist
    - dollarmath
    - html_admonition
    - html_image
    - linkify
    - replacements
    - smartquotes
    - substitution
    - tasklist
  myst_url_schemes: [ mailto, http, https ]
  myst_dmath_double_inline: true
myst_enable_extensions

Extra plugins of MyST for more capabilities.

myst_url_schemes

URI schemes that will be recognised as external URLs in Markdown links.

myst_dmath_double_inline

Allow display math ($$) within an inline context.

HTML-Specific Settings#

#######################################################################################
# HTML-Specific Settings
html:
  favicon: "content/images/favicon.ico"
  use_edit_page_button: true
  use_repository_button: true
  use_issues_button: false
  use_multitoc_numbering: true
  extra_navbar: Powered by <a href="https://www.tudelft.nl/">TU Delft</a>
  extra_footer: ""
  google_analytics_id: ""
  home_page_in_navbar: true
  baseurl: ""
  comments:
    hypothesis: true
    utterances: false
  announcement: "Under Development"
favicon

A path to a favicon image

use_edit_page_button

Whether to add an “edit this page” button to pages. If true, repository information in repository: must be filled in.

use_repository_button

Whether to add a link to your repository button.

use_issues_button

Whether to add an “open an issue” button

use_multitoc_numbering

Continuous numbering across parts/chapters.

extra_navbar*

It will be displayed underneath the left navbar (optional).

extra_footer*

It will be displayed underneath the footer (optional).

google_analytics_id

A Google Analytics (GA) id that can be used to track book views.

home_page_in_navbar

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.

hypothesis

Hypothesis for comments.

utterances

Utterances for comments.

announcement*

A banner announcement at the top of the site (optional).

LaTeX-Specific Settings#

Define the name of the latex output file for PDF builds.

#######################################################################################
# LaTeX-Specific Settings
latex:
  latex_engine: pdflatex
  use_jupyterbook_latex: true
  latex_documents:
    targetname: book.tex
latex_engine

One of ‘pdflatex’, ‘xelatex’ (recommended for unicode), ‘luatex’, ‘platex’, ‘uplatex’.

use_jupyterbook_latex

Use sphinx-jupyterbook-latex for pdf builds as default.

targetname*

Name of the produced book from PDF build (optional).

Launch Button Settings#

Do not change these parameters.

#######################################################################################
# Launch Button Settings
launch_buttons:
  notebook_interface : classic
notebook_interface

The interface interactive links will activate [“classic”, “jupyterlab”].

Information about where the book exists on the web#

#######################################################################################
# Information about where the book exists on the web
repository:
  url: https://gitlab.tudelft.nl/opentextbooks/how-to-manual/
  path_to_book: ""
  branch: master
url*

Online location of your book.

path_to_book*

A path to your book’s folder, relative to the repository root (optional).

branch*

Which branch of the repository should be used when creating links (optional).

References#

Do not change these parameters.

#######################################################################################
# Add a bibtex file so that we can create citations
bibtex_bibfiles:
  - references.bib
bibtex_bibfiles

File with all the citations used in the book.

Advanced and power-user settings#

Do not change these parameters.

#######################################################################################
# Advanced and power-user settings
sphinx:
  extra_extensions: [...]
  local_extensions: [...]
  recursive_update: false
  config: [...]
extra_extensions

A list of extra extensions to load by Sphinx (added to those already used by JB).

local_extensions

A list of local extensions to load by sphinx specified by “name: path” items.

recursive_update

A boolean indicating whether to overwrite the Sphinx config (true) or recursively update (false).

config

key-value pairs to directly over-ride the Sphinx configuration.

More Information#

Find more information about _config.yml: