Jupyter Notebooks are a popular format with data scientists and analysts.
You can use the familiar Jupyter Lab environment to blog with Jupyter Notebooks.
Whenever a Jupyter Notebook is added or updated in the
notebooks folder of your site, it will be published as a blog post.
- In your GitHub repository, click the Settings tab at the top of the page, click Actions > General in the left menu, choose Allow and click Save
- Check that your repo has a file named
.github/workflows/folder. If it doesn’t, you can add the file from here.
Check out the Blog tutorial to learn how to automatically blog with Jupyter Notebooks.
Hugo Blox Builder has a large number of front matter options which can be used to specify page metadata and page features.
The following default front matter options will be set for each notebook when it is imported:
title- attempt to get the title of the blog post from the top-level heading in the notebook. Therefore, we recommend making the first cell of the notebook a Markdown cell with a top-level Markdown heading in the form
# My Blog Post Title.
date- defaults to the date that the notebook was imported as a blog post
slug(the URL of the page) - defaults to the filename of the Jupyter Notebook after being transformed into lowercase and spaces replaced with hyphens
You can override these front matter options and add further options to your notebook by specifying options under the
front_matter section of your notebook’s metadata field.
Jupyter formats the notebook metadata field in JSON, rather than YAML which is used by Hugo. Hence, you may find it helpful to use an online YAML to JSON converter to convert Hugo’s front matter options into the right format for Jupyter notebook.
Remember to click the tick button to save changes to the metadata field after making changes to it in Jupyter Lab:
Notebooks will be automatically imported whenever you add or change a notebook in the
However, if you wish to manually run the importer, such as after resolving an error, you can do so by clicking Actions > Import Blog Posts > Run Workflow > Run Workflow:
Overwrite existing blog posts
If you update an existing notebook in the
notebooks folder, you may want the changes to propagate to the published blog post.
By default, the importer tool won’t overwrite existing blog posts. To allow this, update the
academic command in
.github/workflows/import-notebooks.yml to add the