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.
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.
Create a Git repository
mkdir nb2hugo-demo cd nb2hugo-demo
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 = "firstname.lastname@example.org" [[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
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
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:
Now, to publish your notebooks, you just have to add them to the notebooks directory in your Git repository.