Change Log

Change Log#

v0.15.1 - 2023-03-13#

(full changelog)

Bug#

This release is a minor update to alert users of jupyter-book to sphinxcontrib-bibtex #322 when building bibliographies with docutils>=0.18,<0.20 installed.

Bug: Using docutils>=0.18 results in breaking the page html layout when using sphinx-book-theme on pages that include a bibliography directive.

v0.15.0 - 2023-03-07#

(full changelog)

This release updates sphinx-book-theme to version 1.0.0

The full release notes for sphinx-book-theme==1.0.0 can be found here

Thanks to all the contributors that worked on this major update to sphinx-book-theme

v0.14.0 - 2023-02-28#

(full changelog)

This release updates many of the underlying software packages used by jupyter-book including major updates to myst-nb and myst-parser which power jupyter-book. This release also brings compatibility with sphinx v5.

A big thank you to all contributors and maintainers of these underlying packages. There have been many major updates that will flow through to jupyter-book with this release.

A migration assistance page has been setup to assist users with updates to your configuration and highlights a few of the common breaking changes which are discussed with examples.

Package Updates#

  • #1842 updates myst-nb moving from myst-nb~=0.13.1 to myst-nb~=0.17.1. This incorporates three major updates to myst-nb which in turn incorporates changes to the underlying myst-parser moving from myst-parser~=0.15 to myst-parser~=0.18.

  • #1842 enables compatibility with docutils>=0.15,<0.19

  • #1842 supports sphinx5

  • #1842 incorporates updates for sphinx-design, sphinx-thebe and sphinx-book-theme.

Docs#

Contributors to this release#

(GitHub contributors page for this release)

However this excludes the many major contributions in underlying projects which are documented in the table below.

Package

Contributions

myst-nb

contributors

myst-parser

contributors

sphinx-design

contributors

sphinx-thebe

contributors

sphinx-book-theme

contributors

v0.13.2 - 2023-02-07#

(full changelog)

Maintenance and upkeep improvements#

Documentation improvements#

Contributors to this release#

(GitHub contributors page for this release)

@AakashGfude | @alcrene | @benjaoming | @choldgraf | @chrisjsewell | @codecov | @da5nsy | @dependabot | @firasm | @fmaussion | @fortierq | @jbusecke | @jedbrown | @leodrivera | @matthew-brett | @maxbane | @MaxGhenis | @mmcky | @paugier | @phockett | @pradyunsg | @pre-commit-ci | @rafmudaf | @rkdarst | @root-11 | @salma-emara | @stevejpurves | @stoffprof | @welcome | @Zethson

v0.13.1 - 2022-08-16#

(full changelog)

This minor release includes improvements to the project documentation and includes the following fixes:

Fixes and Maintenance#

  1. #1750 improves compatibility with sphinx>=5.

  2. #1774 fixes an issue that enables math when using the singlehtml builder

v0.13.0 - 2022-06-02#

(full changelog)

This release contains some major UI and visual style upgrades for HTML output, and introduces some breaking changes in a few directives and in the structure of the HTML. See below for major changes.

New and Breaking ‼#

  1. #1442 Use Sphinx Design instead of Sphinx Panels. We have migrated from sphinx-panels to sphinx-design, as sphinx-panels is no longer actively maintained. This also brings in several improvements to the same component functionality that was in sphinx-panels. See the components documentation for more information on upgrades and usage.

  2. #1679 Update Sphinx Book Theme to v0.3. This brings in several major upgrades to the theme’s behavior and structure. It significantly changes the structure of the output HTML (in particular, the sidebars and article header), so if you defined custom CSS rules, double-check that they still apply correctly.

    See the Book Theme release notes as well as the Book Theme changelog for more information.

  3. #1693 Removes support for sphinx<=4. This will likely only be applicable to you if you were explicitly pinning Sphinx to a version less than 4.

v0.12.3 - 2022-03-28#

(full changelog)

This is a minor release, primarily to fix a bug where incorrect Jinja version pinning leads to broken builds. It also updates our build system to use flit and follow the pyproject.toml standard.

Here are the main merged PRs:

v0.12.2 - 2022-02-21#

This is a minor release that bumps the versions of several dependencies in Jupyter Book (see below for details).

(full changelog)

Enhancements made#

Updated dependencies#

v0.12.1#

This release provides bug fixes and updates when building PDF via LaTeX including improved styling for code output cells. It also includes infrastructure for using Jupyter Book with ReadTheDocs.

New#

  • ✨ NEW: Allow running on ReadTheDocs PR #1422

  • ✨ NEW: Upgrade to sphinx-jupyterbook-latex~=0.4.6 PR #1538

v0.12.0#

New#

The primary change in this release is to update the requirements of jupyter-book from sphinx>=2,4 to sphinx>=3,<5 to support sphinx>=4 via #1448.

This includes upgrades to underlying packages:

Documentation has also received updates and fixes.

Thanks to @bryanwweber, @chrisjsewell, @choldgraf, @gabri470, @jmshea, @joelostblom, @mmcky, @patrickmineault, @TomasBeuzen

Deprecations from upgrade to myst-parser#

v0.11.3#

This release enables the use of the singlehtml builder and updates sphinx-thebe and sphinx-book-theme

New#

  1. [builders] Add access to the singlehtml builder via the CLI [PR #1418]

Upgrade#

  1. sphinx-thebe is now version 0.0.10

  2. sphinx-book-theme is now version 0.1.3

v0.11.2#

This release introduces sphinx-multitoc-numbering for consistent numbering across a part/chapter book structure. It also includes improvements to pdflatex output, updates to the documentation and various maintenance tasks.

New#

  • [html] Add sphinx-multitoc-numbering package to provide consistent numbering when organising a book by parts and chapters. This is enabled by default* but can be switched off in the _config.yml file. [PR #1326]

Upgrade#

  • [pdflatex] UPGRADE: Upgrade to sphinx-jupyterbook-latex==0.4.2 which enables support for the tableofcontents directives and improvements to pdf compilation via LaTeX.

v0.11.1#

This release included two minor patches brought in via updates to sphinx-external-toc and jupyterbook-latex.

v0.11.0#

(full changelog) | GitHub contributors page for this release

This is primarily a documentation and under-the-hood update, but it comes with an important change to the way that Table of Contents are structured. See below for more information.

Breaking ‼#

  • Table of Contents. The Table of Contents infrastructure is now handled by the Sphinx extension sphinx-external-toc. This comes with a more structured format for _toc.yaml through the introduction of jb-article and jb-book formats. In order to convert your book’s TOC to the new format, you may run the following command:

    jupyter-book toc migrate _toc.yml -o _toc.yml

    This command includes -o which will update your current _toc.yml file to work with the latest jupyter-book release.

    See the Table of Contents documentation for more information.

New#

  • The _toc.yml file now has support to use glob to add files based on a pattern to the table of contents. This is added using the glob key where you would usually specify a file or url.

    root: intro
subtrees:
- entries:
  - file: doc1
  - url: https://example.com
  - glob: subfolder/other*

    this matches any documents that start with other that are contained in subfolder. [Fixes Issue #1038]

  • Input files to the _toc.yml no longer need to be just ipynb, md, rst. You can now use custom file types as an input such as py files. (Fixes Issue #1064, Issue #1175)

  • The jupyterbook toc command has now been converted to a collection of tools. It was originally setup to read a collection of files and then build a _toc.yml. The equivalent of this command is now:

    jupyter-book toc from-project

    There is also an additional helper tool that builds a collection of files from a user written _toc.yml file using

    jupyter-book toc to-project

v0.10.1 2021-03-02#

full changelog | GitHub contributors page for this release

This is a minor update to include recent improvements made to MyST-NB

New#

  1. An experimental MyST-NB feature that enables loading of code from a file for code-cell directives using a :load: <file> option. Additional information is available in the myst-nb documentation

Upgrades#

Maintain#

v0.10.0 2021-02-01#

full changelog | GitHub contributors page for this release

This update focuses on new syntax features for MyST markdown, as well as a new configuration to enable MyST extensions. See below for more details.

New#

MyST Parser version 0.13.x

The MyST-NB and MyST-parser have both been upgraded. This comes with support for new syntax and a new configuration mechanism (see below for some examples).

(see also the myst-parser changelog for more information about the syntax additions)

New myst extension configuration

The myst_extended_syntax configuration is now deprecated, in lieu of a more flexible extension mechanism. You may now enable individual myst extensions by adding them to the following section of your _config.yml file:

parse:
  myst_enable_extensions:
    - <list-of-extensions>

See the MyST syntax extension section here for more information.

Citations and references configuration

This version comes with a version bump to sphinxcontrib.bibtex v2.1.*. This introduces new configuration for connecting your bibfiles (no longer using the bibliography directive), and makes the citation resolution process much more stable and dependable.

See Citations and bibliographies for more information, and the sphinxcontrib.bibtex documentation for more information about updates in the latest version.

TOC depth numbering

You can now set the depth of numbering (e.g., 3.2 vs. 3.2.1) via the the numbered flag in your Table of Contents. See the table of contents documentation for more information.

New MyST syntax#

MyST Markdown substitutions**

Substitutions allow you to define variables in markdown, and insert them elsewhere in your document. This lets you change the variable value and have it automatically update throughout your book. This is on by default. See Substitutions and variables in markdown for more information.

Automatic HTML links

The linkify extension will automatically identify “bare” web URLs, like www.example.com, and add hyperlinks; www.example.com. This extension is on by default.

Smart Quotes

The smartquotes extension will automatically convert standard quotations to their opening/closing variants:

  • 'single quotes': ‘single quotes’

  • "double quotes": “double quotes”

This extension is off by default. See this documentation for more details.

Typography replacements for common characters

The replacements extension will automatically convert some common typographic texts, such as +- -> ±. This extension is off by default. See this documentation for more details.

HTML admonitions

By adding "html_admonition" to myst_enable_extensions, you can enable parsing of <div class="admonition"> HTML blocks to sphinx admonitions. This is helpful when you care about viewing the “source” Markdown, such as in Jupyter Notebooks. For example:

<div class="admonition note" name="html-admonition">
<p class="title">This is the **title**</p>
This is the *content*
</div>

See HTML admonitions for further information. This extension is off by default.

Deprecations#

myst_extended_syntax is deprecated

See above for new configuration details.

Colon fences now behave like directives

The colon_fence extension (replacing admonition_enable) now works exactly the same as normal ``` code fences, but using ::: delimiters. This is helpful for directives that contain Markdown text, for example:

:::{admonition} The title
:class: note

This note contains *Markdown*
:::
Bibliographies no longer use a path to a bibtex file

See above for new configuration details.

v0.9.1 2020-12-22#

This is a minor release to issue v0.9 to PyPI and updates a broken link that prohibited the v0.9.0 PyPI release action.

v0.9.0 2020-12-09#

(full changelog)

This release includes a number of new features, improvements and bug fixes. There is also a new gallery of jupyter-book projects available.

New#

  • 👌 IMPROVE: Option to exclude every file not in the toc. (docs, #1123, @alex-treebeard)

  • ✨ NEW: Enable the use of local Sphinx extension via _config.yml. (docs, #1102, @mmcky)

  • ✨ NEW: Enable custom builder passthrough. This is an advanced feature that enables the use of additional sphinx builders via jupyter-book that may be provided by an extension. (docs, #1094, @mmcky)

HTML:

  • 👌 NEW: Add dirhtml builder. This enables the use of the dirhtml sphinx builder when using jupyter book. (docs, #1092, @choldgraf)

LaTeX:

  • ✨ NEW: Add --individualpages option for pdflatex builder. This option enables building individual (pdflatex) files for each page of the project. Note: Further work is ongoing to improve the styling and formatting of pdflatex output. (docs, #944, @mmcky)

Maintain#

  • 🔧 MAINTAIN: Pin sphinxcontrib-bibtex to ~=1.0 until compatible with recently released v2 (#1138, @choldgraf)

Upgrades#

Bugs fixed#

Deprecated#

  • 🗑 DEPRECATE: removing expand_sections for toc as it is deprecated in sphinx-book-theme. (#1073, @choldgraf)

v0.8.3 2020-10-12#

This is a relatively minor release with bugfixes and under-the-hood improvements.

Bugs fixed#

Upgrade EBT dependencies#

v0.8.2 2020-09-19#

(full changelog)

Improved#

sphinx-panels version bump to v0.5, which adds several new content blocks including {tabbed} content. #972

v0.8.1 2020-09-09#

New ✨#

Add jupyter-book create --cookiecutter (thanks to @TomasBeuzen)

This adds a --cookiecutter option to jb create, to allow users to use the Jupyter Book cookiecutter to create a book template.

The cookiecutter is suitable for more advanced users that want to create a ready-to-go repository to host their book that includes pre-populated metafiles such as README, LICENSE, CONDUCT, CONTRIBUTING, etc., as well as GitHub Actions workflow files.

Fixes 🐛#

This release contains numerous improvements, to the documentation and code, to address issues noted by you guys:

  • Fix issues with single document builds (e.g. pdflatex) and relative path resolutions

  • Ensure sphinx-book-theme is loaded on PDF builds (to allow the use of the margin directive)

  • Allow execution timeout: -1 and execute_notebooks: off to be valid in the _config.yml

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

Contributors to this release#

(GitHub contributors page for this release)

@AakashGfude | @amueller | @bmcfee | @brian-rose | @cedeerwe | @choldgraf | @chrisjsewell | @codecov | @consideRatio | @cpjobling | @drscotthawley | @emdupre | @firasm | @jni | @jstac | @lewtun | @MaxGhenis | @mmcky | @najuzilu | @nathancarter | @phaustin | @ptcane | @samteplitzky | @tobydriscoll | @TomasBeuzen | @welcome

v0.6.4…v0.7.0#

(full changelog)

Merged PRs#

Contributors to this release#

(GitHub contributors page for this release)

@AakashGfude | @akhmerov | @alejandroschuler | @alexnakagawa | @amueller | @andrewsanchez | @asteppke | @betatim | @boazbk | @brian-rose | @cedeerwe | @choldgraf | @chrisjsewell | @consideRatio | @cpjobling | @Cyb3rWard0g | @dafriedman97 | @DavidPowell | @dhruvbalwada | @emdupre | @epacuit | @firasm | @flying-sheep | @foster999 | @gharp | @goanpeca | @grst | @hamelsmu | @jasmainak | @jgm | @jmason86 | @jni | @joergbrech | @johngage | @jpivarski | @jstac | @kyleniemeyer | @malvikasharan | @martinagvilas | @MasterScrat | @mathieuboudreau | @matteoacrossi | @mgeier | @mikdale | @mmcky | @mwcraig | @mwouts | @najuzilu | @NatalieThurlby | @ofajardo | @oscarys | @parmentelat | @peaceiris | @pgadige | @phaustin | @prabhasyadav | @psychemedia | @Racooneer | @rahuldave | @rossbar | @roualdes | @saulomaia | @TomasBeuzen | @trallard | @xldrkp | @yuvipanda

v0.6.3…v0.6.4#

(full changelog)

Enhancements made#

Bugs fixed#

Other merged PRs#

Contributors to this release#

(GitHub contributors page for this release)

@choldgraf | @emdupre | @GasperPaul | @javag97 | @joergbrech | @melaniewalsh | @psychemedia

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

Contents