Building a Blog on the Notion API
Update: it’s live. This page you’re seeing is now rendered through this latest version of my website.
I’m going to try re-implementing this site using the Notion API as a backend. I’ve had a couple of blog posts saved as drafts in various places, and I’d like to reduce the friction to posting new things here.
Project Goals
Most Important
- Minimize time to the blinking cursor: The blinking cursor is always there; I think then name of the game is to just get there faster.
- Integrate with the Notion API: The site is currently a Rails application. I love Rails but I also think it’s time to try something new here; particularly, I’d like to edit posts using Notion and not have to deploy or log into my admin site to add a new post.
- Tight Feedback Loop: ideally we can use ISR or push so that I don’t have to redeploy whenever something changes.
- Aesthetic: Should look and feel similar. SEO/etc should not be compromised at all.
Nice to Have
- Would be nice to draw on my iPad and be able to make the posts show up and update right away.
- Code quality: use notion’s types as much as possible so that we get static checking - this will make the renderer much easier to implement/iterate on.
- Simple migration process: I’d have to check the Postgres database this site runs on, but ideally it doesn’t take more than a few minutes to migrate all the data over.
Features
I’d like to at least keep feature parity with what’s live right now. That includes:
Renderer
Pages / Sections
Features and Fixes
Log
Monday, September 5, 10a
Ok I went for JSX instead of straight to html and that simplified things a lot. Feels like it’s halfway there now, but I need to get back to my day job for now.
One of the biggest unlocks is rendering notion blocks → jsx → html, instead of directly from notion → html.
Type hints in action:

Another nice realization is that we don’t have to implement the entire HTML spec. Only the types outlined in the Notion API client.
Sunday, September 4, 10:55pm


Sunday 9/4, 6pm
First version of Notion block → html renderer

Sunday morning
- It seems like this is mostly straightforward, but I do wonder how easy rendering HTML is going to be. Notion has the concept of a Block, which is sort of like an HTML node.
- Found a couple of potential renderers:
- I still think there are some open questions around how to properly render from Notion blocks → HTML. Might end up having to write a simple renderer here.
- Update: yeah, had to do that.