tl;dr: check the source of this site.
Motivation
Having read this blog, I am convinced to host my personal blog.
There are 2 ways to build a self-hosted blog in general: using a popular blog builder such as WordPress, or build the HTMLs from "scratch".
I decided to use a proper frontend framework for the job, Gatsby, because I can.
Background
Gatsby is a multi-page website generator based on React. The stack can be visualized as follows:
As prerequisite, one is expected to know HTML, CSS, JS, TS and React.
Challenges
Before starting this project, I had no knowledge of Gatsby or SSG at all. Thus the lessons I learned may also be helpful for any other developers who are new to it.
Static Site Generation
As one of my previous projects used Next.js, I am know server side rendering(SSR) very well. However things are fundamentally different for Gatsby as it is only a static site generator(SSG). This basic difference has trapped me for many times. So here I record the differences between SSG and SSR:
| SSR | SSG |
|---|---|
| runs server side code at runtime | no server at runtime |
| must be deployed with a server | deployed as plain html/css/js bundles |
| fetches data in real-time | requires rebuild to change the data |
How does SSG fit the need to build a full-blown website then? Apparently with a custom server you can host both webpages and data in the same place. For example, the blogs as data can be stored in the server as JSON/Markdown etc, while the pages are served in another directory on the server. But with Gatsby the data must be consumed by the pages during buildtime.
Fetch Data by GraphQL
During buildtime, Gatsby spins up a server providing all the data required. The pages then query this server to fetch the portion of data they each needs. Remember this step only happens during buildtime.
Localization
For me, it is necessary to serve audience from both English background and Chinese background. Thus my blogs need to be served in both English and Chinese. This is one of the considerations I took when I decided to make my own blogger as no other blogger is popular in both China and outside.
Coming to the implementation part, there are several tools which may help.
Gatsby Plugin I18next
To localize isolated strings on a random page, i18next is a perfect solution. There are some subtleties worth mentioning.
The localization requires an instance of i18next provided by a context. Hence it is vital to wrap every page and component by the context provider. This blog offers an elegant approach.
Manual Translation
For some content-rich pages, like blogs, I tend to edit them in markdown which does not play well with i18next. Hence my approach is to sort out the generation of blogs myself.
Heading Anchor
A very useful markdown enhancement is the anchor of the headings. This is one of
the basic requirements for table of contents. However, gatsby-plugin-mdx is
not shipped with this support.
According to this blog, this feature can be easily added.
Deployment
The last problem is to host the site. There are generally 2 methods to choose:
- host on a self-managed server
- host on a public cloud
I happen to know a couple of free hosting services: Github Pages and Cloudflare Pages. The latter requires one to have a personal domain registered with Cloudflare though.