Using Notion API to export pages for Hugo+Github Pages website

3-minute read
day-to-day • practical-application
Photo by  Douglas Lopes  on  Unsplash | width=500

Writing can be so hard! For those not naturally gifted at writing, it takes a lot of effort for the right words to flow. I started to write after being inspired by Rachel Thomas’ post on ‘Why you should blog’.

You are best positioned to help people one step behind you.

It’s true and I wanted to have a ‘home’ for my ideas, thoughts and learning journey.

I’ve been using Github for years now, both for work and personal project. Naturally I was drawn to the idea of using Github Pages to host my blog.

My initial workflow for writing included the use of Notion for jotting down content ideas, keeping reference links to interesting articles; and writing/developing using my trusty VS Code. This workflow worked for me at the start, but I wanted to better track and manage my projects with a leaner and more flexible workflow from a code development and knowledge sharing perspective. I’ve also been on the go a lot lately without my personal laptop, so this makes the ‘knowledge sharing’ bit a tad bit inconvenient.

Content Management Revamp

TL;DR

Changes made:

  1. Write and manage content in Notion directly instead of markdown editor

  1. Use Notion’s page properties to hold metadata needed to organise articles in Notion, Github and Github Pages at various stages of the content lifecycle

  2. Automate publishing of ready articles

    A daily cron job was set up to:

    • pick up Notion pages with Status="Ready to Publish"

    • convert Notion pages into markdown files

    • commit and push changes and files to Github

    • change Status of published Notion pages from Ready to Publish to Published

Now I can focus writing and experimenting while the publishing efforts are taken care of!

Non TD;LR version

Notion has grown massively over the years and it’s not difficult to see why - its simple yet powerful and flexible. Aside from using it for planning, idea dumping and task tracking, I’ve started using it to draft points for my blog articles when I’m on the go. Rather than manually transferring them to markdown for editing, I started tinkering with the idea of using Notion for drafting articles and pushing final versions to Github Pages.

That’s when I came across Nik van der Ploeg’s post on exporting Notion pages to his Hugo-powered blog. I could relate to his backstory on notion-blog-exporter and his tool was exactly what I was looking for:

  1. pulls specific Notion pages and all associated images and links

  2. reformats pages into markdown and include front matter from Notion page properties

  3. commits and pushes changes to Github which gets reflected in Github Pages

I was hoping to use his tool but soon realise that notion-blog-exporter (built 14 months ago at the time of this post) was leveraging on notion-py, an unofficial Notion API which was reverse engineered from Notion’s private API. I noticed that Notion had released its official API in May 2021 and I was keen on using their official API. In addition, notion-py was no longer actively maintained.

Hence I decided to build my own version of the exporter, with the help of https://github.com/ramnes/notion-sdk-py - Python wrapper for the official Notion API.

Summary: Out with the old, in with the new workflow

Summary of workflow changes from old to new

In a nutshell, here’s how I’ve made my writing workflow leaner and more flexible.

The first version of the exporter tool notion-export-md was built quickly with my baseline requirements in mind. I’ll continue crossing off my wish list as I continue to write more over the new year 2022!