Under the hood

Updated: 2020-06-29

This part documents how this website is built and maintained. Hopefully it can be helpful for the like-minded.

Let's start with a little bit history ...

Note-taking, evolved

Back in school, I hate taking notes using the physical notebooks, because half of the content may gradually become outdated, the other half should be expanded but it is hard to copy-and-paste. The end result is - I almost never ever read them again.

Then came Microsoft Word, copy-and-paste was no longer a problem, but I found it painful to do the formatting manually. ASCII arts looked much better than inconsistently formatted word documents to me.

Soon we were required to use LaTeX for assignments, I loved the fact that everything was written in plain text, and formatting was done automatically after compilation. However it can be an overkill if you are not dealing with math.

Another problem about LaTeX was that my notes were compiled into a pdf sitting on my local disk, it was hard to share on the web. Some of the computer science (except for math) related notes were migrated to Sphinx, the Python doc tool using reStructuredText as markup language.

I stumbled upon Nanoc when I was trying to setup a simple website for a side project, it was the first static site generator I used, and I immediately fell in love with in, because I write plain-text markdown files, and define formats and styles in CSS, and the website was pre-generated so extremely low maintenance. Until I needed to add some customization, I realized I need to learn Ruby. I have nothing against Ruby but based on my observation of the tech world trends, I did not have a good reason to spend time on it (I'm glad I did not). Jekyll is another Ruby based tool used by GitHub.

Blog or Notes

I tried WordPress, but quickly gave up: (1) I did not want to manage my own server and database (2) it was not plain text (3) not a big fun of PHP.

At the time I was learning Node for fun so I looked for something in Javascript. Ghost was the one I tried next, however similar to WordPress, I still need to maintain my server, after several outages I decided to move on.

I also used several online blog sites before WordPress and Ghost. My biggest problem with Blog is that every post has a timestamp attached to it, the mission is to capture my thoughts at exactly that moment, after I click the "publish" button, I feel it is so wrong to go back and revise it, the only fate of the posts is to grow old and be forgotten. And let's face it, for technical content, no one really cares about what do you think at the moment, or "how to install Ubuntu 12.04" serval months later. Blog is linear. On the contrary, keeping a set of notes is more like building a knowledge graph iteratively. Externally I expect the traffic to my site is mostly redirected from Google search, and hopefully the notes can help solve a concrete problem, instead of for me building a big following crowd.

Stick to Javascript (and settled down with Gatsby)

After that I used Hexo for a while. Like Nanoc it was a static site generator using Markdown, but in Javascript so I felt more comfortable to read the source code and make customizations when needed. The site was served on S3, cheap and low maintenance, nothing to complain.

For a brief time I used Gitbook, but later it pivoted to be a content publish platform instead of the awesome open-source tool set, so I abandoned the ship.

Eventually I migrated to Gatsby, and that is how this site is built, for now. The primary reason is that Gatsby is based on React, arguably the most popular web framework, though it is hard to predict how long that will remain. The front-end world is moving frustratingly fast. Another minor reason is GraphQL, at the time it sounds like a revolution comparing to REST, but it is yet to be seen how far it can go.

Check the Stack page for the full list of tools and services I'm using.