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 https://nb2hugo.netlify.com/. Its corresponding repository is https://github.com/vlunot/nb2hugo-demo/. 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 > README.md << "EOF"
# nb2hugo demo site

This repository shows how to combine [nb2hugo](https://github.com/vlunot/nb2hugo/), [Hugo](https://gohugo.io/) and [Netlify](https://www.netlify.com/) to easily blog with [Jupyter](https://jupyter.org/) notebooks.
The resulting site is available at https://nb2hugo.netlify.com/.
EOF

git add README.md

git commit -m "Initial commit"

[master (root-commit) 25b77a7] Initial commit
 1 file changed, 4 insertions(+)
 create mode 100644 README.md

git remote add origin https://github.com/vlunot/nb2hugo-demo.git

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 https://themes.gohugo.io/, 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 https://gohugo.io/ for quickstart guide and full documentation.

git submodule add https://github.com/halogenica/beautifulhugo.git base/themes/beautifulhugo

Cloning into '/home/v/Workspace/nb2hugo-demo/base/themes/beautifulhugo'...
remote: Enumerating objects: 2361, done.[K
remote: Total 2361 (delta 0), reused 0 (delta 0), pack-reused 2361[K
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 = "https://nb2hugo.netlify.com"
DefaultContentLanguage = "en"
title = "nb2hugo demo"
theme = "beautifulhugo"

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

[Author]
  name = "Vincent Lunot"
  website = "https://www.vincent-lunot.com"
  email = "vlunot@gmail.com"
  
[[menu.main]]
    name = "Blog"
    url = ""
    weight = 1

[[menu.main]]
    name = "Tags"
    url = "tags"
    weight = 3
EOF

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/default.md
 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 > build.sh << "EOF"
FILES="$(find notebooks -type f -name '*.ipynb')"
for f in $FILES
do
    nb2hugo $f --site-dir base --section post
done
hugo -s base
EOF
chmod +x build.sh

git add .

git commit -m "Add Netlify configuration files"

[master b04d78f] Add Netlify configuration files
 3 files changed, 8 insertions(+)
 create mode 100755 build.sh
 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 ./build.sh 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.