Blogging with Jupyter notebooks and Hugo

We are going to introduce a simplified workflow for publishing Jupyter notebooks on a website generated with Hugo. The python package nb2hugo will be used to convert the notebooks to markdown pages. The process will be fully automated thanks to Netlify. Once everything configured, you will just have to push your Jupyter notebooks to a Git repository to get them published on your website.

Demo site

A demo site is available at Its corresponding repository is You can just fork this repository to create your own blog, or make your own repository from scratch. To help you understand the overall process, the following sections will show step-by-step how this demo repository was created.

Structure of the project repository

We are going to use the following structure:

  • the root of the repository will contain the Netlify configuration files,
  • the base directory will contain a template of the Hugo website,
  • the notebooks directory will contain the Jupyter notebooks.

Once everything ready, you will just have to add your new Jupyter notebooks to the notebooks directory in your Git repository.

Step-by-step instructions

Create a Git repository

mkdir nb2hugo-demo
cd nb2hugo-demo
git init
Initialized empty Git repository in /home/v/Workspace/nb2hugo-demo/.git/
cat > << "EOF"
# nb2hugo demo site

This repository shows how to combine [nb2hugo](, [Hugo]( and [Netlify]( to easily blog with [Jupyter]( notebooks.
The resulting site is available at
git add
git commit -m "Initial commit"
[master (root-commit) 25b77a7] Initial commit
 1 file changed, 4 insertions(+)
 create mode 100644
git remote add origin
git push -u origin master

Add a website template

hugo new site base
Congratulations! Your new Hugo site is created in /home/v/Workspace/nb2hugo-demo/base.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from, or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit for quickstart guide and full documentation.
git submodule add base/themes/beautifulhugo
Cloning into '/home/v/Workspace/nb2hugo-demo/base/themes/beautifulhugo'...
remote: Enumerating objects: 2361, done.
remote: Total 2361 (delta 0), reused 0 (delta 0), pack-reused 2361
Receiving objects: 100% (2361/2361), 6.31 MiB | 2.62 MiB/s, done.
Resolving deltas: 100% (1323/1323), done.
cat > base/config.toml << "EOF"
baseurl = ""
DefaultContentLanguage = "en"
title = "nb2hugo demo"
theme = "beautifulhugo"

  subtitle = "Easily convert your Jupyter notebooks into a blog"
  dateFormat = "January 2, 2006"

  name = "Vincent Lunot"
  website = ""
  email = ""
    name = "Blog"
    url = ""
    weight = 1

    name = "Tags"
    url = "tags"
    weight = 3
touch base/content/.gitkeep
touch base/layouts/.gitkeep
touch base/static/.gitkeep
touch base/data/.gitkeep
git add .
git commit -m "Add basic website template"
[master 85cf4ff] Add basic website template
 8 files changed, 33 insertions(+)
 create mode 100644 .gitmodules
 create mode 100644 base/archetypes/
 create mode 100644 base/config.toml
 create mode 100644 base/content/.gitkeep
 create mode 100644 base/data/.gitkeep
 create mode 100644 base/layouts/.gitkeep
 create mode 100644 base/static/.gitkeep
 create mode 160000 base/themes/beautifulhugo

Add configuration files for Netlify

echo -n 3.7 > runtime.txt
echo nb2hugo > requirements.txt
cat > << "EOF"
FILES="$(find notebooks -type f -name '*.ipynb')"
for f in $FILES
    nb2hugo $f --site-dir base --section post
hugo -s base
chmod +x
git add .
git commit -m "Add Netlify configuration files"
[master b04d78f] Add Netlify configuration files
 3 files changed, 8 insertions(+)
 create mode 100755
 create mode 100644 requirements.txt
 create mode 100644 runtime.txt

Create a directory for notebooks

mkdir notebooks
touch notebooks/.gitkeep
git add .
git commit -m "Add notebooks directory"
[master 58dff12] Add notebooks directory
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 notebooks/.gitkeep
git push

Create a new site on Netlify

Go on Netlify and create a new site.
In basic build settings, set ./ as build command and base/public as publish directory:

Netlify build settings

Now, to publish your notebooks, you just have to add them to the notebooks directory in your Git repository.