I've published the source codes for my website and the library notion-x that I built for it. However, I don't have time to provide detailed guidance on how to use them**!** In this note, I discuss the reasons behind this and some tips or problems I encountered during the theme development. I believe this is more beneficial than merely providing a step-by-step guide. Let's learn together and build a site like mine!

<aside> ⚠️

This post contains a large amount of text. I understand it may be difficult to follow, but I don't have another way to express these detailed ideas.

</aside>

<aside> 👉

Demo of notion-x and all components on this website

</aside>

TL;DR;

  1. I tried in order Jekyll → Gatsby → 11ty → Next.js. I end up with Next.js as a SSG + Notion as a CMS.
  2. If don’t want to use Notion, you can try Obsidian. However, this post isn’t for the link with this tool.
  3. Why Notion? → You cannot find another WYSIWSG that is more powerful than this one. It supports a quick full-text search and we can integrate it with Next.js.
  4. Why not Notion official APIs? → It’s slow + limit the number of requests each second, you will meet too many 429 errors.
  5. To use unofficial APIs (the APIs Notion uses on their website), I customize react-notion-x to adapt the styles I want. I call this customized as notion-x. I use this libray for all my projects.
  6. Why Next.js? → It’s react based, it’s quick and we can use Vercel for deploying our app easily and quickly.
  7. For different types of posts/collections, I use different Notion Databases. For example, notes, topics, projects, tools, bookmarks have different databases.
  8. The biggest problem you may encounter when deploying your site is the Serverless Function Execution Timeout. Vercel and other free services only support 10s of SSR. You have to make your codes run faster as much as you can. That’s why we use unofficial APIs and other tips.

A short history

<aside> ⚠️

I wrote this section based on my memory of the frameworks I've tried. They may have been updated since the time I wrote this section. It would be best to check their official sites for any new changes.

</aside>

I initially created my site with Jekyll, popularly known as a static site generator, when you search for "creating your own personal website". This is why from version 1 to version 3, I used Jekyll to develop this site.

However, as the size of the notes grew and the need for regular content changes increased, the build time also escalated. Thankfully, Jekyll enhanced their incremental regeneration, which was a game-changer. It allowed for building only the recent changes, significantly reducing the time and improving the workflow!

I soon realized that extensive customization of my site required understanding of Ruby, which I found challenging. Consequently, I migrated my site from Jekyll to Eleventy, a framework that offers in-depth customization using only JavaScript. I've documented my process of building an 11ty website from scratch in this detailed note.

Another appealing feature of Eleventy is the ability to use Nunjucks to write your site's template. This language is similar to what Jekyll uses, so the transition wasn't overly time-consuming. In fact, it took me just a month and a half to fully migrate from version 3 to version 5. As for why I didn't migrate to version 4, please continue reading.

Before discovering 11ty, I experimented with Gatsby, a rapidly growing static site generator (SSG) framework. I was highly impressed by its rendering speed. Even minor changes in the code could be seen instantly in the browser without any latency, a feature common to single-page applications and other React apps.

I had completed about 60% of a site build with Gatsby when I encountered difficulties with inserting images in markdown files at custom positions and sizes. I needed my notes to be flexible to effectively express my ideas, while maintaining a clean and clear design. Due to these issues, I abandoned Gatsby and switched to using 11ty instead. I also noted the whole process in this note. Moreover, if you want to migrate from Wordpress to Gatsby, another note of mine may be useful for you too.