Blogging

Creating a blog with notebooks

Background

Blogging with notebooks can offer a dramatic quality of life improvement over writing in Markdown, especially for blog posts that contain code. Previously, there were no static site generators that supported Jupyter Notebooks as a first-class authoring medium. This previously led us to create fastpages (now deprecated), which extended Jekyll to enable blogging directly with Jupyter.

Enter Quarto

However, there now exists Quarto, a wonderful publishing system with rich support for authoring via Jupyter Notebooks.

Some helpful resources on getting started with Quarto:

The Quarto Homepage
Creating A Blog With Quarto: This page helps you get started with creating a blog.
A Gallery of Quarto Sites: Good reference examples of using Quarto.
The Quarto Website: The Quarto website is built with Quarto and they use some of its advanced functionality. It is instructive to look through this project to understand how Quarto works.

You don’t need nbdev to blog with notebooks

You do not need to use nbdev to create a blog with notebooks. However, you may wish to:

Incorporate a blog in your nbdev project’s website
Use some nbdev functionality in your blog (testing, exporting etc)

We will discuss these subjects in this article.

Migrating from fastpages

If you previously had a fastpages site, we offer some utilities to help migrate you to Quarto. The migration is not holistic: you will likely have to manually correct some things that we are not able to automate.

Instructions:

Install Quarto
Create a new repo or directory to migrate your blog to
In this new repo, create a quarto blog and install required extensions with the following terminal commands. This will create a minimal project structure for you:

quarto create-project --type website:blog .
quarto install extension quarto-ext/video

Your new repo will have a posts/ directory. This is where you will copy all of your notebook and markdown posts from fastpages. For example, let’s say your fastpages blog repo is in a sibling directory located at ../blog/, you would copy all the relevant posts like this:

Important

Make sure you are in root of your quarto directory before executing the below commands. Furthermore, change the commands as appropriate depending on the location of your fastpages repo relative to your current directory.

cp -r ../blog/_notebooks/* posts
cp -r ../blog/_posts/* posts

Copy all images associated with your posts into the posts/ directory. We have to get our images from several places (due to the way Jekyll and fastpages work):

cp ../blog/images/* posts
cp -r ../blog/images/copied_from_nb/* posts/

Make your posts Quarto compatible with the following command:

nbdev_migrate --path posts

What does nbdev_migrate do?

nbdev_migrate does the following things:

For notebooks

Migrates markdown front matter to raw cell front matter as described here.
nbdev v1 directives are automatically converted to Quarto directives. Note that we convert everything to Quarto directives (nbdev-specific directives are not relevant for this context)
Markdown shortcut for embedding youtube videos and callouts are automatically converted to work with Quarto.

For markdown and notebooks

Automatically creates link aliases so that old links will not break. Jekyll automatically generates URLs differently than Quarto, so this ensures that the Jekyll way is aliased.
Automatically corrects image paths
Makes front matter compatible with Quarto by changing field names and values where necessary

Update the following files:

./.gitignore: we suggest adding_site/ as well as dot files .*
./about.qmd: Add some information about yourself.
./profile.jpg: optionally change the profile picture.

Preview your site with the command quarto preview, and make any necessary adjustments and fix for broken links or Jekyll shortcodes (things with {% ... %}) that need to be converted to Quarto. Search the the Quarto documentation if you need help locating specific Quarto features.

Configuration options: fastpages vs. Quarto

fastpages (which is based on Jekyll) and Quarto offer different options and configurations for individual posts and at a site level. The tables below enumerate some of the most important features of fastpages and how they map to Quarto. Each link in the last column is specific to the relevant feature.

Post-level options

Jekyll Front Matter	Quarto	Notes
toc: false	Same	There are more options in the Quarto docs
badges: true	n/a	No support yet
comments: true	see notes	Quarto docs
categories: [fastpages, jupyter]	Same	Quarto docs
image: images/some_folder/your_image.png	Same	Quarto docs
hide: false	draft: true	Quarto docs
search_exclude: true	see notes	Quarto docs
title	Same
description	Same
sticky_rank	Not supported	Quarto docs

Site-level options

Jekyll site config	Quarto	Notes
title	see notes	Quarto docs
description	see notes	Quarto docs
github_repo	see notes	Quarto docs
url	n/a	Don’t need this
baseurl	n/a	Don’t need this
twitter_username	search page in notes for “twitter”	Quarto docs
use_math	see notes	Quarto docs
google_analytics	website: google-analytics: “UA-XXXXXXXX”	Quarto docs
show_image	n/a	Quarto docs
show_tags	see title-block-categories of page in notes	Quarto docs
pagination	website: page-navigation: true	Quarto docs
annotations	comments: hypothesis: …	Quarto docs

Publishing your blog

Warning

This section is for stand-alone blogs that are not part of a nbdev documentation site. If you want to create a blog within a nbdev documentation site, see this section.

You can publish your site with the quarto publish command. See the docs for more details.

GitHub Pages

If using GitHub Pages, commit your files to GitHub before publish your site. No GitHub Actions are needed, you can use quarto publish instead. If you want to automate your workflow with GitHub Actions, you can follow these instructions

Creating a blog within a nbdev project

In addition to a stand-alone blog that you might build with Quarto, you might want to include a blogging site in your nbdev project. This website has a blog as well! The easiest way to implement a blog is to emulate the directory structure of this folder. The general steps are:

Create a blog/ directory in your notebooks folder.
Create a index.qmd file in the root of the blog/ directory. Here is an example.

The frontmatter the index.qmd file signals to Quarto that you intend to create a blog. For example, here is our front matter:

---
title: nbdev Blog
subtitle: News, tips, and commentary about all things nbdev
listing:
  sort: "date desc"
  contents: "posts"
  sort-ui: false
  filter-ui: false
  categories: true
  feed: true
page-layout: full
---

The listing: field specifies how you want to structure your blog. Feel free to copy ours as-is, but we encourage you to consult the documentation for additional options.

Create a link to your blog on your site’s navbar so people can find it: To add a link to your blog on your site’s navbar, you must edit the navbar section of _quarto.yml to include a link to your blog’s listing page, which is blog/index.qmd in our example. For nbdev, the relevant part of our _quarto.yml file looks like this:

The yaml snippet shown below is an abbreviated version of nbdev’s _quarto.yml file.

website:
  navbar:
    left:
      - text: "Blog"
        href: blog/index.qmd

You can read more about the navbar in the Quarto docs.

Create a folder for each blog post: This is not strictly required, but we recommend this as a way to keep your blog posts and related assets (pictures, videos etc) organized.
Create your first blog post: You can emulate our example or create your own. In each folder, create a index.qmd or index.ipynb file. You can also put images and related assets in the same folder.

Folder structure

Below is an overview of the general folder structure for a blog within a nbdev site:

nbs/blog
├── index.qmd
└── posts
    ├── 2022-07-28-nbdev2
    │   ├── cover.png
    │   ├── index.qmd
    │   ├── ...
    └── 2022-08-25-jupyter-git
        ├── friendly-conflict.png
        ├── index.qmd
        └── ...
    ...

nbs/blog: this is the folder inside your notebook folder that contains the blog.
index.qmd: this is at the root of your blog folder and is the listings page for your blog.
posts/: this a subdirectory for each blog post.
YYYY-MM-DD-.../index.{qmd,ipynb}: this is where you author the content of each individual blog post.

Special considerations for nbdev blogs

In contrast to standalone Quarto blogs, when you embed a blog in a nbdev website there are the following differences:

You can use all nbdev directives in addition to Quarto ones. All nbdev features will be available in your nbdev blog in the same way they work for other pages.
Your site will automatically deploy with GitHub Actions or whatever deployment mechanism you have for your nbdev site, so you do not have to use quarto publish.

Using nbdev features in blogs outside nbdev projects

Warning

This section is for stand-alone blogs that are not part of a nbdev documentation site. If you create a blog within a nbdev documentation site, all nbdev features will automatically work.

If you create a standalone blog with Quarto, a limited number of nbdev features can still assist you. For example, we recommend installing Jupyter git hooks. A list of nbdev features available to you are listed in this article.

Creating A New Blog Site From Scratch

You can use the quarto CLI to setup a new blog project called myblog with the following command:

quarto create-project myblog --type website:blog

You can then preview your blog project with quarto preview. You can also publish your blog using the quarto publish command.

Adding a notebook blog post

To add a notebook blog post to a blog project created with the above commands, you can add an additional folder under posts/ and name the notebook index.ipynb. You will see existing example blog posts that are index.qmd files in sibling folders you can look at for examples. You will need to add yaml front matter to the first cell of your notebook in the form of a raw cell.

For more information about creating a blog with Quarto, see this guide.

FAQ

Do I need to migrate from fastpages?

No you do not. However we will not be actively supporting fastpages going forward.
Will migrating from fastpages to Quarto take lots of manual effort?

You will have to do some manual work to make sure everything looks and works the same, including converting Jekyll shortcodes to equivalent Quarto commands. However, we have automated the biggest aspects for you. Please see Migrating from fastpages for instructions.
I cannot find something in Quarto that does what #collapse_output did in fastpages

Correct, this is a feature that isn’t supported in Quarto yet.
Why am I seeing {% twitter ...%} and {% fn_detail ... %} and other {%...%} commands in my Quarto blog posts?

These are Jekyll shortcodes that you will have to manually migrate to Quarto. For example with the twitter embeds, you can insert the appropriate HTML as recommended by Twitter. For footnotes, you can see these docs. For other items, you should search the Quarto docs for how to enable your desired result.
I created a new blog post and used #| hide but the cell is still showing. What is wrong?

You must use Quarto directives, not nbdev-specific ones. See the difference between the two in these docs. This is because you are blogging with Quarto, not nbdev. The exception to this is you have a blog site in your nbdev project – in that case, nbdev-specific directives will work.
How do I enable comments on my blog posts?

In general, Quarto offers all of the same features and much more than fastpages did, including comments. If you search the Quarto docs for comments, you will see a page for enabling comments.
How do I sort and hide posts? What about the publishing date since that’s not in the filename?

See the Quarto docs on creating a blog as well as listing pages.
How do I customize my site?

See the Quarto docs
How do I do set up RSS Feeds and add particular features to my site?

See the Quarto docs
What does nbdev have to do with Quarto?.

For just blogging, nothing! You can use Quarto for blogging without worrying about nbdev. In the past, we maintained a nbdev related project called fastpages, and are recommending that people migrate to Quarto if possible. Furthermore, nbdev is built on top of Quarto which means much of the functionality is similar. Finally, you can incorporate blogs into a nbdev project site, which we discuss in this section.
For stand alone blogs, why are you directing us to Quarto, can I just use nbdev?

nbdev is built on top of Quarto. For the purposes of blogging, adding nbdev is of little additional benefit if all you want to do is to blog. We decided to keep things simple and let people use Quarto directly instead of trying to abstract aspects of Quarto for blogging. Furthermore, having some knowledge of Quarto can be very helpful in using nbdev!. Lastly, you can still use some nbdev features in your blog, which are listed in this article.