New Blog

November 12, 2023

When I first created this blog in 2019, its inaugural post was titled Overengineering a Blog, which is precisely what I did. I wanted every code block to be a tiny TypeScript playground of sorts. Unsurprisingly, this was a huge pain to maintain, and I lost interest not only in using the interactive features I worked so hard to create but also in writing altogether. I put a colossal amount of effort into a few of the early posts, which made me hesitant to publish anything less polished. Shifting to working from home during COVID brought about a general technology fatigue during which I couldn’t imagine thinking about TypeScript or even being on a computer outside of work hours. The combination of these factors led to the three-and-a-half-year hiatus in posts preceding this one.

Lowering the bar(rier)

In considering relaunching the blog and beginning to write again, I didn’t just want to make the infrastructure easier to maintain; I also wanted to give myself permission to publish posts that don’t take so much work that I burn out on writing for years afterward. Years ago, I was hoping to write mostly opinionated educational content, so I was highly concerned with correctness and credibility, and only dared to write about topics on which I thought I could present as an expert. Now, there’s only one topic I can plausibly claim to be an expert on, so I don’t plan to write a lot of posts with the aim of convincing anyone to do anything. I feel more comfortable now with simply presenting information I find interesting, which makes it much easier to publish.

Minimal design changes

I was tempted to redesign everything, but in the spirit of trying to actually write again instead of spending forever just working on the site, decided not to. I made a few small changes that I’m really happy with:

• Posts on the index page now have an intentional description, rendered in a sans-serif, instead of an arbitrary truncation of the post content. I bought the regular weight of Founders Grotesk for this purpose, which I previously had only in medium for photo captions, footer text, and the About page link. I replaced some of these uses with the regular weight and like the way it lightened things up a bit.
• I removed the light/dark switcher in favor of using the system preference unconditionally.
• Code blocks always use a dark theme instead of switching between light and dark with the rest of the site. I am not anti-light-theme for code but I didn’t like the way it looked in this context. I also updated the dark theme colors to match VS Code’s new Dark Modern, which is the best syntax theme, having recently taken the crown over the previous best, VS Code’s Default Dark+.
• Links in post bodies are now permanently underlined with no hover effect, and have the same color as normal body text. They used to be blue, with an underline on hover.
• I added “newer” and “older” links at the bottom of posts, finding another place to use Founders Grotesk.
• The site footer is simplified, with icons removed. (The Twitter link is gone; the feed icon was replaced with text; the GitHub icon moved to the top to replace the theme switcher.)
• I also stole Anthony Fu’s sliding enter animation. Historically, I have been very opposed to animation that doesn’t serve an important functional purpose, but upon seeing this on Anthony’s blog, I was instantly enamored with it. I’m not sure how I’ll feel once the novelty wears off, but I decided to take a chance on it for now.

After making these changes, I found I was still quite happy with the design. A part of me wanted to switch to a humanist sans-serif body font for technical posts, which I expect to make up the majority of future posts, but I couldn’t give up Heldane for prose. I may experiment with using different typefaces for posts of different categories, but this is fine for now.

Choosing the new stack

The old blog was built with Gatsby. Since I decided to remove all the interactive components, there was no longer any reason to use React (or to have any client-side JavaScript at all) as part of the site generator. (I was not opposed to using React/JSX as my templating language, but without the need to hydrate any statically rendered components, it was not a necessity.) I considered Hugo for its unmatched speed, but decided that Eleventy would be faster for me to configure and customize since I know JavaScript about a million times better than I know Go.

For styling, the old blog used Emotion and Typography.js, which I actually liked quite a bit, but didn’t make sense to use without React or JavaScript. I ported my typography styles to plain CSS and used Tailwind via UnoCSS for the layout.

I also decided to drop Google Analytics. I don’t look at the metrics, and don’t want to be complicit in any privacy harm it may be doing. I might try to self-host a more privacy-focused analytics platform in the future, but I’m ok not knowing anything about the traffic for now.

What I like

• Eleventy is fast and simple. It was extremely easy to get running, learn how to use, and recreate the structure of the blog. The vast majority of my time was spent on porting styles, not on configuring Eleventy.
• Eleventy’s primitive bundler plugin was sufficient to bundle all my vendor CSS (like a reset and Katex styles) into one asset-hashed file and to bundle my generated Tailwind utilities and other site CSS into another asset-hashed file, and write the link tags pointing to those generated URLs. More than good enough without taking a dependency on a full bundler.
• The selection of official and community Eleventy plugins is decent, and where there were gaps, I found it easy enough to hack what I needed into a shortcode. We’re just generating HTML from data, in contrast to Gatsby, which had so many different contribution points and whose overall architectural model eluded me for the entire time I used it.
• Tailwind’s documentation is absolutely top-notch.
• Netlify is still great. After not touching it for 3.5 years, all I had to do was tell it to use a newer Ubuntu, and it picked up the new build system like nothing ever happened.

What I dislike

• Types (whether generated or hand-written, JSDoc or .d.ts) for Eleventy configuration and plugins were almost universally incorrect, an incomplete afterthought, or completely absent. Writing any amount of JavaScript that interacts with the generator is a really poor experience for those who are accustomed to being able to rely on IntelliSense (which feels like, pretty much everyone using any modern JS tools now?).
• It drives me crazy that the search on Eleventy’s docs is its own page, which requires scrolling to the top and clicking on a link, with no auto-complete or live results filtering. It’s a small thing, but so many developer tooling documentation sites have spoiled us with ⌘K Algolia-powered search that not having it feels like a significant paper cut now.
• I’m not sure what I got out of using UnoCSS over Tailwind CSS directly, even after reading the page that was supposed to explain it to me. It talks a lot about customization, but everything I customized in the config can be done with Tailwind’s config too. Honestly, I used UnoCSS only because I heard positive buzz about it, but I found its documentation a little lacking (for example, it doesn’t explain that theme.breakpoints is just a renaming of Tailwind’s theme.screens, while seemingly every other theme option keeps the same name?), and I really missed Tailwind’s excellent VS Code extension. UnoCSS has a VS Code extension too, but it doesn’t activate on Liquid templates, and seemed not to be reading my customizations from my config file (perhaps because I named it uno.config.mjs instead of uno.config.js?). All it did was underline every occurrence of the word “my” in my Markdown files. After discovering the extension has no documentation whatsoever that I could use to attempt to debug these problems, I uninstalled it.

Content on deck

I recently outlined a post detailing the history and design considerations of type-only imports, a TypeScript feature I worked on. I think that will be interesting for, you know, a very niche audience, but it would benefit from being able to lean on a separate technical explainer of TypeScript declarations and symbols, which is something I wish someone had already written when I was learning the compiler API. So I plan to start working on those two soon.