How I Built This Site
March 7, 2023
I'm not sure why, but it seems to be some kind of law of nature that every developer's blog has a post describing how they built it. I guess there's just something about the process of setting up a website and getting it online that makes nerds want to share their process. So here's my obligatory post about how I built this one.
Static Site Generators
Way back in 2016, when I built my first blog, I decided to use Jekyll to generate the site. There's some definite advantages to this approach - you write your posts in markdown, and Jekyll generates all the HTML for you. It takes some of the manual labor out of getting something online, and Github Pages supports Jekyll sites out of the box, which means if you have some basic command line knowledge, you can have something online in minutes.
The downside of using a static site generator like Jekyll, Gatsby, Hugo, or any of a million other options, is that you're locked into the workflow of that framework. This can be fine if you just want to focus on writing blog posts, but as soon as you want to jump off the rails, you're stuck trying to configure the generator instead of spending time on your site. So for this site, I decided on a simpler approach.
Just Write HTML
That's right, I decided to just write some HTML. One of the main reasons I built this site was to have a place to showcase little projects and experiments, which means that my pages won't always adhere to a particular format. And at the end of the day, HTML is the lingua franca of the web - it's what all browsers ultimately need to see in order to render content. It's a little bit of extra work to get set up, but there are major benefits in terms of simplicity. I can preview all my pages without any extra tooling, I have complete control over styling and layout, and - critically - there's no need for npm anywhere in my repo. As a convenience, I added a Live Server plugin to VSCode, and with this going I can see how the site will look in real time as I write posts and fiddle with layout.
I had an ulterior motive, too, which was simply to learn HTML better. Back in the old days of the web, no one was making sites without having a basic grasp on HTML, but these days, that's not necessarily the case. Even developers can get quite far without every writing a single line of raw, unadorned HTML. We've got site generators, templating engines, and component-based frameworks like React. All these are great for certain applications, but the net effect of all these tools on me was that I never really got a handle on basic HTML. Often, when I've sat down to build a page for an app, I've been unsure of what elements to use to get it to look how I want. So "just" using HTML is a great way to force myself to put in some reps on the markup that underpins the internet.
I spent a little bit of time building a sample post with some lorem ipsum text first, getting things looking the way I wanted. And now, when I'm ready to make a post, I just copy that template file, change a few things like the title and date, and write the HTML in the article tag. It's funny how easy this is - I think us software geeks have a tendency to overcomplicate simple things in the never-ending quest to eliminate repetition and drudgery from our work.
Making It Pretty
I did allow myself one concession to convenience. I chose to use Tailwind CSS to style the site. This is somewhat counter to the stuff I said above about the benefits of just using straight up HTML, but in this case, I think the tradeoff is well worth it.
If you're not familiar with Tailwind, it's a utility-first CSS framework. In essence, what this means is that Tailwind predefines a boatload of CSS classes, and you do styling by adding these classes to each of your elements. Unlike frameworks like Bootstrap, these classes are utility classes, and in most cases, they are named just like the CSS they ultimately result in. For example, if you add the whitespace-nowrap class to an element, it's equivalent to a whitespace: nowrap directive in your CSS file. The flex class just adds display: flex, and so on. The net effect, for me at least, is that using Tailwind feels very much like using vanilla CSS, but with some guiderails and sensible defaults to keep things pretty. I felt like Tailwind struck a good balance between helping me make things look good while also giving me the final say over how things looked.
Tailwind does introduce a build step into my project, which I would have preferred not to have to deal with. To make this a little nicer, however, Tailwind ships a standalone cli, which prevented me from having to deal with npm (always a win in my book). I have a small script which runs the CLI in watch mode in my repo, and running this while I write a post makes the whole thing fairly seamless.
Tailwind isn't perfect. One thing I've noticed as I've started to get more familiar with it is that you wind up with a lot of noise and repetition in your HTML. For example, here's a snippet of the source from my landing page:
<div class="h-screen m-auto flex justify-center items-center m-12">
<div class="container m-auto p-4">
<div class="mb-16 lg:mb-12 flex flex-col gap-4 lg:flex-row md:justify-center items-center">
<img class="w-2/3 h-2/3 lg:w-1/4 lg:h-1/4 rounded-full mb-4 sm:mr-4" src="/assets/me_thumbnail.jpg"
alt="Eric's profile picture">
<div class="lg:mb-12 text-center lg:text-left">
<h1 class="text-6xl md:text-7xl lg:text-8xl 2xl:text-9xl font-bold py-2 text-neutral-300">Eric Coleman</h1>
<p class="text-4xl md:text-5xl lg:text-6xl 2xl:text-7xl text-neutral-400">Hi! I'm Eric. I make cool stuff.</p>
</div>
</div>
<div class="lg:px-32 gap-4 flex justify-around flex-col lg:flex-row items-center">
<a href="/posts/"
class="text-4xl md:text-5xl xl:text-5xl 2xl:text-7xl text-neutral-300 hover:text-neutral-400 mb-4">Blog</a>
<a href="/cv.html"
class="text-4xl md:text-5xl xl:text-5xl 2xl:text-7xl text-neutral-300 hover:text-neutral-400 mb-4">CV</a>
</div>
As you can see, there is a lot of information in each of the class definitions. Especially in cases where I'm changing sizes of things like text based on screen size, you wind up with lots of noise, and if you're utilizing the same size for multiple tags, you need to repeat the class definition. This got a little annoying as I was iterating on the design of the site, especially when I had the same style that I wanted to change in multiple places. But it's a small price to pay for the flexibility of styling things individually, and as I get everything tweaked to my liking, it's very easy to group multiple Tailwind classes together using their @apply directive in my stylesheet. The upside of the "class soup" is that you can tell just by looking at the HTML how something is going to be styled, which is good for me as I get a better handle on CSS and Tailwind.
Oh - one other thing. It turns out to be incredibly important to add this CSS directive to the head of pages that you want to be responsive:
<meta name="viewport" content="width=device-width, initial-scale=1.0">
This "famous" viewport tag is apparently well-known to frontend devs, but I didn't learn about it until after I'd already styled the whole site without it, which resulted in a lot of rework. But I guess that's exactly the kind of learning I was hoping to get out of building this site, so that's OK.
Another key component of making the site look nice was PrismJS, which I used to do code syntax highlighting. This is another case of something that's just pleasantly simple - you just add a stylesheet for the theme you like and add their script in a script tag on articles where you want code highlighting. I chose a theme that looks like my VSCode Solarized Theme, so you're getting the real Coleman Experience when you see code on this site.
Putting It Online
I bought epiccoleman.com ages ago, I think even before I had my Jekyll blog. For a long time this domain was pointed at that old Github Pages site via a forwarding mechanism specific to Google Domains. The problem with that was that while navigating to epiccoleman.com would take you to my blog, the domain name in the address bar would change over to the github pages url. That was always annoying, but I never bothered fixing it.
I'd heard good things about Netflify for hosting static sites, so I decided to give it a whirl for my new site. So far, it's fantastic - I'm currently deploying by simply dropping the site/ folder from my repo into the Netlify web page, and it works seamlessly. It's about as easy and simple as I could possibly hope for, so major points to the Netlify team for that. So far, hosting is free, and their free tier limits are generous enough that I doubt I'm going to run up against them soon. It's also nice that I'm not locked into their platform in any way - if I change my mind, all I have to do is upload my site to some other hosting provider.
One other neat thing about Netlify is that they have built-in analytics, which require absolutely nothing to be added to my site. They monitor traffic on their end, and can give me information about things like page views and failed requests without me needing to do anything. That's $9/mo, and to be honest I might not keep using it at that price, as I don't see this site getting a ton of traffic, but it is kind of neat to see how things like a post on Twitter or LinkedIn actually do drive some traffic here.
Netflify was a mild pain to hook up to Google Domains, but I think that's more on the end of Google than Netlify. Turns out the right combination of directives was an A record pointed at the Netflify load balancer IP, and a CNAME for the wwww version of the domain. But that's a set once and forget forever kind of thing, so hopefully I never need to mess with it again.
What's Next
I have a few plans in the works for things to add to the site, like a page to host projects and some other ideas for blog posts that might belong in their own section. It also would be cool to have a place for people to enter their email so I could build a mailing list (although it might be humbling when nobody signs up 😅). So far, I think I have a pretty decent starting point to build a cool little spot on the net.
Stay tuned for more! Later.
If you liked this post, sign up for my email list via Substack so you can get notified whenever I publish a new post!