Contents

Change Log

v0.8.0 2020-09-01

(full changelog)

You spoke, we listened!

Version 0.8.0 of Jupyter Book, incorporates a bottom-up refresh of the entire Executable Books Project (EBP) stack, with tonnes of bugs fixes, improvements and new features 🎉

The documentation describes all this new functionality in full detail, but below we shall try to outline the major changes and additions.

Breaking ‼️

The jupyter-book/jb executable should work almost identically to in v0.7.5, and all existing books will generally build as before (open an issue if not!).

The key change is that jupyter-book page is no longer available. Instead you can now pass a single file path to jupyter-book build, as opposed to a directory, and it will build your single page (thanks to @AakashGfude). See Build a standalone page.

Another thing to note, is that if you are using “bare” LaTeX math in your documentation, then this will only render if you activate in your _config.yml:

parse:
  myst_extended_syntax: true

See the math documentation for details.

New and Improved ✨👌

Jupyter Book v0.8 incorporates all the great new features available by moving from:

  • MyST-Parser v0.9 to v0.12 (see its CHANGELOG.md)

  • MyST-NB v0.8 to v0.10 (see its CHANGELOG.md)

  • This also enabled, Sphinx v2 to v3

Here’s the headlines:

Windows support

Continuous Integration (CI) testing is now run against Windows OS throughout the EBP stack. The fixes this entailed, mean that Jupyter Book can now be run on Windows with minimal issue (see Working on Windows)

Extended “Markdown friendly” syntaxes

MyST Markdown directives offer a high degree of extensibility, to add all the features we might need to create a scientific document. However, they are not (yet) very well integrated with external editors, like the Jupyter Notebook interface. Extended syntax parsing to the rescue!

By enabling in your _config.yaml:

parse:
  myst_extended_syntax: true

You can access to a number of Markdown friendly syntaxes, which extend the CommonMark specification:

  • ::: fenced admonitions render Markdown as standard (see new style admonitions).

  • HTML images are correctly handled, allowing for control of size and style attributes, and Markdown style figures extend this for captions and referencing (see images and figures).

  • Definition lists are what you see here and provide a simple format for writing term/definition blocks (see definition lists).

  • LaTeX math is now intrinsically supported, meaning that it will rendered correctly in both HTML and LaTeX/PDF outputs (see math and equations).

Custom Notebook Formats

Want to write your notebooks as RMarkdown, Python files, ….? Jupyter Book now supports linking any file extension to a custom conversion function, run before notebook execution and parsing. See the custom notebook formats and Jupytext documentation, which itself is written in RMarkdown!

Execution Configuration

Execution and caching of notebook outputs has been improved, to make it more consistent across auto and cache methods (cache execution is now also run in the notebook directory) and provide numerous configuration options, including:

  • Running the execution in the local directory or in a temporary directory.

  • Setting the execution timeout limit, at a global or notebook level.

  • Allowing errors across all notebooks, or at a notebook or cell level.

  • Removing stderr/stdout outputs or logging warnings when they are encountered

  • A directive for displaying execution statistics for all notebooks in the book (status, run time, etc)

See the execution documentation for more details.

Code Output Formatting

More cell outputs are handled, including Markdown and ANSI outputs, and you can use cell metadata to set image size, style, captions and references. See formatting code outputs.

Build options and error reporting

The jupyter-book build command includes additional options/flags for controlling the build behaviour, such as verbose (-v), quiet (-q) and nitpick mode for checking references (-n). See the command-line interface documentation for more details.

sphinx-panels integration

The sphinx-panels package is not provided directly in the Jupyter Book distribution. This adds additional functionality for creating web based elements, such as gridded panels and dropdown boxes. See the Panels and Dropdowns section for details.

Fixes 🐛

Among the numerous fixes:

  • Code cell syntax highlighting now works for all Jupyter kernels.

  • User configuration is now recursively merged with the default configuration, and no longer overwrites an entire nested section. You can also use jb config sphinx mybookname/ to inspect the sphinx conf.py which will be parsed to the builder.

More to come 👀

We have many more improvements planned, check back in this change log for future improvements.

Also please continue to provide us feedback on what you would like to see next. See our voting for new features page.

v0.7.5 2020-08-26

✨ NEW: This release introduces the new “Comments and Annotations” feature, powered by sphinx-comments. See this documentation section for further details.

Important: this version also pins the myst-nb dependency to v0.8. Previous versions erroneously allow for the new v0.9, which is not yet strictly compatible with jupyter-book (coming very soon!)

v0.7.0…v0.7.4

(full changelog)

Enhancements made

Bugs fixed 🐛

Documentation improvements 📚

API Changes

  • ✨ NEW: Adding - chapter entries to _toc.yml #817 (@choldgraf)

  • removing config file numbered sections to use toc file instead #768 (@choldgraf)

Other merged PRs

v0.6.4…v0.7.0

(full changelog)

Merged PRs

v0.6.3…v0.6.4

(full changelog)

Enhancements made

Bugs fixed

Other merged PRs

v0.6.0…v0.6.3

(full changelog)

Enhancements made

Bugs fixed

Maintenance and upkeep improvements

Documentation improvements

Other merged PRs

v0.6.0 (2019-09-17)

Full Changelog

Implemented enhancements:

Fixed bugs:

Closed issues:

  • Jupyter Notebook can’t close a running notebook #317

  • Building book fails with a jinja2.exceptions.TemplateNotFound error #310

  • serving non- md/ipynb content #295

  • Broken links #259

  • Missing file error #253

  • Multicursor sometimes only deletes one line when there’s spaces #251

  • Release summary for v0.6 #331

Merged pull requests:

v0.5.2 (2019-07-26)

Full Changelog

Implemented enhancements:

  • implement removecell for markdown cells #192

Fixed bugs:

  • yaml.load() is unsafe #230

  • Update documentation links that are broken #224

  • pip installation: jupyter-book or jupyter_book? #184

  • Figure out why Gemfile and Gemfile.lock are causing issues #154

  • Page turn link URLs missing .html #140

  • Errors when running on Windows #137

  • Docs aren’t being updated from master #136

  • toc help is incorrect #132

Closed issues:

  • Update docs about how to hide code cells #240

  • Is it possible to export Word, PDF and other formats? #228

  • Make it clear in the documentation that the full docker path needs to be specified, not the relative path #220

  • Why do we have “content” directory inside the “_site”? #219

  • mismatch in docs and functionality #214

  • Double check that generate\_toc.py is getting copied properly #210

  • jupyter-book cli does not work as stated in the getting started guide #208

  • Unable to install jupyter-book in conda environment #206

  • Error if kernelspec missing #195

  • Clarify the CLI help statements #146

  • jupyter-book upgrade also modifies requirements.txt #130

Merged pull requests:

v0.5 (2019-05-13)

Full Changelog

Implemented enhancements:

  • Markdown guide refers to Highlightjs but Rouge is used #183

  • Get codecov working #153

  • Add thebelab button to every code cell #117

  • Add an option / config for analytics tracking? #115

  • Add support for nbinteract #82

  • Scrolling in subtitle column #173

Fixed bugs:

  • Page turn links to external sites are broken #186

  • Code cell pre-wrap causes split lines #182

  • problems building with images #124

  • Problems with local build instructions on Mac (and perhaps other ‘nix platforms) #123

Closed issues:

  • Plots not showing in ipynb files #179

  • jupyter-book is missing from the binder requirements #166

  • Binder and Thebelab not working for demo book #155

  • Errors building HTML #152

  • Non --demo option seems to fail #120

  • Error on notebook.py with inconsistent and DEFAULT_STATIC_FILES_PATH. #108

  • add requirements to setup.py #105

  • Add a CONTRIBUTING.md #99

  • Explore using a cookiecutter for the site #87

  • Use a Python CLI instead of Make #42

  • Autogenerate toc #40

  • Force permalinks to be lowercase and replace space and ‘_’ with ‘-‘ #35

  • Extra buttons to support #32

  • Use a submodule for notebooks folder #14

  • Jupyter Book version v0.5 #175

Merged pull requests:

v0.4.1 (2019-02-09)

Full Changelog

Closed issues:

  • Disappearing None #98

  • Inquiry: Plotly interactive plots in a Jupyter Books? #93

  • iframe not rendering #91

  • thebelab uses the wrong kernel #90

  • An option to embed a link on sidebar logo #77

  • Scrollbar overlaps with TOC table (on Linux) #75

  • Unwanted leading white space at the beginning of code block #73

  • Standard badges rendering too big #65

  • Give a shout-out to bookdown #63

  • Make it clearer how to customize the look and feel of the site #61

  • Recommend a way to make citations #60

  • Highlight active section in right sidebar #55

  • Allow people to put YAML in their content files #51

  • Site Search #39

  • Conversion from old system to new #37

  • Support “versions” of a book #31

  • Book is not rebuilding #29

  • Feature request: right-side navbar auto-scroll #24

  • generate_summary_from_folders doesn’t output prefixed numerals #23

Merged pull requests:

v0.2 (2018-10-23)

Full Changelog

Closed issues:

  • Feature request: Search Bar #25

Merged pull requests:

v0.1 (2018-10-20)

Closed issues:

  • Calling newer version of nbclean than is available on pypi #21

  • Changing MathJax Size of only Blocks #19

  • Change Color of Links #18

  • Enhancements to pull from the DS100 textbook #17

  • Hidden Code Blocks #13

  • MathJax Rendering Issues #12

  • Generate textbook not finding README.md #11

  • Fork and clone may not be the best workflow #10

Merged pull requests:

* This Change Log was automatically generated by github_changelog_generator

Glossary