Using Notion as a CMS for my new personal blog

I’ve been wanting to revamp my personal site for a while now. I was never happy with what I previously had and I don’t have a natural gift for design, so I was putting a lot of pressure on myself to come up with a site that looked great, felt great and was easy to use. But because design isn’t something that comes easily to me, I’ve been continuously putting it off and have ended up with a stagnant site that I haven’t been publishing any blogs to because I would have been too embarrassed to share them anywhere. So I recently sat down and decided to make a start on my new site, with those two things in mind - I want to start publishing some blogs and I want them to look nice.

I need blogging to be easy

If I want to write blogs regularly then I knew I was going to need to find a workflow to enable that, so what were my options?

Write static HTML pages straight into my site

This is the most basic option with the least tooling involved. In my repo I could create a folder called blog and create a child page for every article I want to write.

I ruled this out immediately - writing raw HTML isn’t a very fun experience and I don’t want to have to do it frequently.

Write them in markdown and transform them

This is how I was working in the previous iteration of my site. Write the articles into an md file and then transform them to HTML in a build step before publishing a new version of the site.

This is an okay option but honestly I would prefer not to have to deal with making the changes in code - creating a new git branch and opening an IDE just to write a blog seems like more friction than I want to deal with.

Use a CMS

A CMS seems like the obvious choice then, Sanity and Prismic both offer free tiers and are easy to work with. I can write blogs in a browser, so from any device, and I can set up web-hooks to trigger a new build and deployment of the site whenever I publish or edit an article.

Great - so I guess the only barrier to entry now is that I have to learn how to use one of these tools and then figure out their api so I can hook it into my site…

Notion

I’ve been using Notion for note-taking both on my personal projects and for work for a couple of months now and I’ve absolutely loved it! It’s lead me to completely ditching physical notebooks - which can be forgotten at home on the occasions I venture into the office or left behind in a meeting room - and I haven’t looked back. It’s great for keeping my information organised and up-to-date, sharing it with others and most importantly I’ve gotten used to using it regularly and I’m quite fast at getting my thoughts down in it.

So when I learnt that Notion has an API which can be accessed at no extra cost that can expose my content, I instantly knew it was the right choice for me.

Getting Notion content into a webpage

So I know I want to use Notion to write my blogs and I know I can get hold of the content via their API, but there was one problem I wasn’t sure how to solve: a Notion page is in a custom format - it’s close to markdown and a lot of markdown formatting is supported, but the API doesn’t give you a markdown page. So how do I parse/render it onto a webpage?

After a quick web search I found the answer in a library called react-notion-x. This repo contains a few packages to make working with Notion in React extremely easy - there is a Notion client for communication with the API and a NotionRenderer component to render the api result as a react component:


import * as React from 'react'
import { NotionApi } from 'notion-client'
import { NotionRenderer } from 'react-notion-x'

export default () => {
  const notion = new NotionApi()

  const recordMap = await notion.getPage('067dd719a912471ea9a3ac10710e7fdf')

  retrun (
	  <NotionRenderer recordMap={recordMap} fullPage darkMode={false} />
  )
}

All seems fairly straightforward. I’m planning on using Next.js, so it should be easy enough to create a template blog page component that exports a getStaticPaths function that can find the slugs for all the articles and a getStaticProps function that retrieves the record map for every page and passes that into the page component via props.

Making it look nice

By this point I know that I can use Notion to structure my blog content nicely - it’ll deal with headings, paragraphs, lists etc. so all that’s needed is to make it look nice in the browser.

I’m a web dev, so I should be able to make a great website right?

I consider myself to be, if not a great, at least a capable web developer - I know my way around some semantic HTML, I can generally get CSS to do what I want and I’m pretty handy in a few JavaScript frameworks - so I should be able to make a great website then, right? That’s what I’ve always told myself and then have been disappointed when my final product has been lacking in the polish - the wow factor - that I was expecting it to have. It’s not usually a problem, because in my day job I work with designers who know what they’re doing and my personal projects rarely have an intended audience other than myself. But I want people to come to my blog - and I want them to have a great experience when they do - so clearly I need to do something different.

My first thought was that I could hire a designer on fiverr - that way I get a nice design but I’m still doing all the dev work myself. But how important is that really? Is it worth it for me to pay someone else so that I can code up their design, just so that I can say ‘I made that’?

Transitive bullshit

The author of the react-notion-x library that I talked about above, Travis Fischer, has an open-source repo for setting up a Next.js project that gets its content from Notion. All you have to do is create a copy of his publicly accessible demo Notion page, fork the repo and edit the values in the repo config. That’s it. That’s all I had to do and I had exactly what I was after - a Notion-backed blog that was intuitive to use and that looked great. The demo repo contained some instructions for getting your site deployed on Vercel. Vercel wouldn’t be my first choice for hosting a personal project - I’d rather host on AWS. But when I tried to set it up on AWS Amplify, I was getting a strange error executing next build which I couldn’t figure out after half an hour or so of trying and Vercel worked straight away, so I figured I could come back to AWS in the future if Vercel became a problem for me.

So in only a couple of hours, I’d gone from an idea to a deployed blog site.

Final steps

I had a few small things I wanted to do before I considered the project ‘done’.

There wasn’t too much I wanted to change about the look over the default site. I made a couple of small changes to the CSS in the project but mainly I swapped out the images for some I found on Unsplash - Notion has an Unslpash integration built into the editor, so it’s super easy to use and all of those changes can be made outside of the codebase.

After that I removed the example blog posts and copied over my one existing blog post What is JWT?, again adding a nice cover image from Unsplash.

Finally I updated the DNS records for my domain jackohara.io, which I manage in Cloudflare to point at Vercel’s name servers, and helpfully Vercel have some documentation on just how to do that.

Final thoughts

Overall I love my new site. I think it looks great, but mostly it’s so easy for me to write and publish new blogs. On top of that, I still have complete control over the codebase and can make any changes I want to the appearance.

If you want to know more about my stack or have any questions about what I’ve written, feel free to get in touch!