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).
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
: