Jonathan Lam

Core Developer @ Hudson River Trading

Blog

On this blog

On 4/18/2021, 4:21:01 PM

Every so often I look at my personal website and think, Hmm. This is cringeworthy. And every so rarely I end up rewriting the website. Six years after writing my first personal website, this force of creativity and personal growth has led to this third-generation personal website and blog. (gen 1 blog, website; gen 2 blog, website) While it certainly doesn't look like much, there's still a good deal to say about it.

The overall layout and design of the website, or lack thereof, is the most noticeable. I've tried hard to keep previous websites somewhat visually appealing, and I was fairly proud of the minimalist design of the previous website when I first made it. More recently, I discovered that my sense of design is awful, and that my primary interest in CS is not in web development or design (but rather more systems programming or compiler design). The uninteresting design is somewhat of a testament to a functional design. It's fast and it looks good-enough -- perhaps better than a busy website when you have to have to design for half a million aspect ratios, which is only partially mitigated by responsive CSS libraries like Bootstrap. A summary of these design choices is found on the FAQ.

The backend is much more interesting. As with the previous websites, the only major concern I had in mind before writing the website was that it should be static, so it can be hosted on GitHub Pages (and the superb Fast.ly CDN) for free. Also as before, the goal was to build up the web application more or less from scratch (at least sticking away from major front-end frameworks). As I began coding the website, the following concerns came up:

SPA or multi-page application? The modern trend clearly favors the former, but it involves a lot of extra code and costly change-detection that I don't need for this simple application.
How do I keep my code DRY? For a multi-page application, even having the same header on each page requires code reuse. At first, I tried to get away with using <iframe>s, but this felt like an inefficient HTML4 workaround. This led to the creation of a build system centered around the Pug templating engine. This means writing the essential page content in Pug files, and having a Node.js script compile the pieces into a static HTML page.
How should I keep metadata about the website's pages? There are many options out there; YAML seems convenient, so I chose it. This YAML stores an index of all pages to be built, including information about: what Pug template to use, what data needs to be supplied to the Pug template, where the file should be built, and submodules (described below).

Only after considering these questions did I understand why Jekyll made its design choices. (For the unaware, Jekyll is a Ruby-based build system that generates static websites, and GitHub pages supports building Jekyll websites automatically. For context, I've tried using the jekyll-now variant in the distant past, but never got too involved with its inner workings.) Jekyll also uses YAML for configuration; it chose Ruby as the scripting language of choice (as opposed to my use of Node), and it uses Markdown and Liquid for templating as opposed to Pug. Jekyll allows you to easily have a feed of blog posts, several static pages that show up in the navigation bar, and static assets as necessary; this is a fairly standard use case and allows users to very quickly set up a standard website very quickly.

So that's it. Long story short, this website is built using a custom static webpage generator developed on the spot that ended up converging more or less to Jekyll.

There's not much different, except perhaps that every emitted HTML page, and the permalink at which the HTML will be emitted, is explicitly listed in a YAML index file. This is as opposed to scanning the source files and automatically where to build them as Jekyll does (iirc). Both approaches have their advantages; the advantage to this way is that you have all the output paths in a single file, rather than distributed throughout the front matter of all your blog posts.

In the case that the website has multiple subfolders with many files, the way to avoid cluttering up the index file is to create "submodules," which are essentially index files of a subdirectory. I created this specifically to handle having a blog that follows the same index file format. I think this solution scales nicely for deeply-nested subfolders.

And that's about it! The source code for this website can be found on GitHub at @jlam55555/jonathan-lam-website. Some lesser details:

When building the blog, there was the issue of what to make the permalinks: should posts URLs be numbered (like xkcd), titled (like Jekyll), or both (like Stack Overflow, in which case the title is functionally useless)? I went with numbers numeric indices because they are simple, short, ordered, and wouldn't cause problems if the post title changes.
As of now, there is a script to build the website (I don't have a file watcher set up, so every build is manually triggered). A local test server is created by statically hosting the built webpages using Express.
At the time of writing, there is only one instance of JS on the core website: the 404 page (to get the URL). (Two if you include MathJax on the previous blog post.) Similarly, the only CSS on this website are to modify the sizes of the <html> and <body> elements.
This website looks great in w3m! Almost as good as it looks in the browser! Wow!

Building this build system was all very spontaneous, but I think it's likely that all the build systems (sh scripts, make, cmake) and package management systems (npm, pip, mvn, and a cursed situation I accidentally created with apt) that I'm exposed to for school projects are affecting me. I'll probably end up writing about some of them in the future.