Upcoming changes in v2.3 (edit - now released)

v2.3 will be released soon-ish, and you can play with the upcoming functionality by installing from master. Here’s a summary of some of the key changes to know about.

New processing system

The big change is that now rendering your docs is much faster. The time for the notebook processing stage for nbdev’s own notebooks has gone down from 24 seconds to 1 second! In addition, the latest quarto prerelease has also been sped up. The combination should dramatically cut your doc rendering time, possibly by even an order of magnitude!

The reason that nbdev’s notebook processing is faster is that we’ve written our own parallel processing system, instead of relying on quarto’s ipynb-filters. This system is automatically run whenever you call nbdev_docs or nbdev_preview. It processes each of your notebooks, and places the result in a directory called _proc in the root of your repo. These processed notebooks are exactly what quarto uses as input. Therefore, you can cd into that directory and run quarto render, quarto publish, etc, and it’ll all “just work”. This is particularly useful if you use something other than Github Pages for publishing your docs, since quarto publish supports numerous other services.

When you run nbdev_preview, we now run our own watchdog server which watches for any changes, so you get live/hot reloading in the browser. Try changing and saving any notebook whilst preview is running, and you’ll see the results reflected in your browser immediately without any manual refresh required.

New _quarto.yml approach

Previously, nbdev auto-generated your _quarto.yml for you and updated it based on changes to settings.ini. In v2.3 we still auto-generate it if it’s missing, but we no longer auto-update it. Instead, there’s a small nbdev.yml that’s auto-updated from settings.ini and is included into your _quarto.yml. But other than that, you’re free to customise _quarto.yml however you like, and your changes won’t ever get trampled by nbdev.

New quarto sidebar auto generation

Previously, nbdev auto-generated your sidebar for you, assuming you had custom_sidebar = True in your settings.ini (which was the default). However, quarto (v1.2, currently in prerelease) now provides its own automatic sidebar system. Therefore, we’ll be deprecating custom_sidebar = True, and you should switch to using Quarto’s approach. We’ll be providing a way to automate this change so most users won’t have to do anything manually except run a single line in the shell.

nbdev’s own docs are now using this approach, so take a look at the nbdev repo if you’re curious about how any of is working on the nbdev site.

PS: You may also be interested in checking out info about the changes in the v2.2 series.


Another interesting upcoming change is that you can create rendered .py scripts. These are regular python .py files, except that:

  • Rather than just having the extension .py, they’ll have an extension like .qmd.py
  • They contain a module docstring containing frontmatter (i.e three hyphens on a line, then some yaml, then another three hyphens on a line).

These scripts are run when your site is rendered. Anything that they print to stdout becomes a new file in your site. The name of the file is the same as the name of the .py script, but without the .py extension. For instance, in nbdev itself, the home page is created by a script called index.qmd.py, which you’ll find here.

You’ll also see that file includes the line:

from nbdev import qmd

nbdev.qmd is a small module that has some convenient functions for creating .qmd documents, such as div and img. You can see examples of their use in index.qmd.py.

Hot/live reloading even works with these .py scripts – so as soon as you save the script, you’ll see the new output in your web browser! I haven’t tested everything yet, but you should be able to use this approach for creating any kind of file - e.g. you could create an SVG file dynamically.

PS: Once you’ve run nbdev_preview or nbdev_docs you’ll find your rendered document in the _proc directory, along with all of your processed notebooks. This might be helpful for debugging.


2.3 has now been released.