This Blog's Stack

Let's examine this blog's stack by following a request. This is a static site.

You're reading this on https://whyfivetimes.com/content/this-blogs-stack/, so, let's say we open a new tab and type that URL into the browser address bar, and hit enter.

whyfivetimes.com is a custom domain name that I purchased and registered on Porkbun. Why Porkbun? I read positive reviews, I like a tool that does a specific thing and does it well, and the functionality and pricing was just fine for me (cheap, and basic domain management for few domains). Cloudflare was busy rejecting me for a technical role at the time, too 🙃 (I think they've built some great things).

So, you attempt to access that custom domain, and Porkbun ultimately sees your request come through. Porkbun does offer static site hosting, but as of writing, it isn't free. There are many free options, so I evaluated a few. I had been hearing good things about Render, so I decided to give their free static site hosting a try. When you create a static site service in Render, it provides you with a domain, in my case, that domain is https://why-five-times.onrender.com. Render then provides instructions to point requests to your custom domain to this provided domain. In Porkbun, I added ALIAS and CNAME records pointing to whyfivetimes.com and *.whyfivetimes.com respectively to the Render domain (why-five-times.onrender.com).

So, so far:

• We've typed https://whyfivetimes.com/content/this-blogs-stack/ and hit enter
• The DNS system has done its thing:
  • It took our request over to Porkbun where the whyfivetimes.com domain is registered
  • It saw a pointer to the Render why-five-times.onrender.com domain, and is sending our request to the Render servers that accept requests to that domain name

Okay, so we've made it to Render.

Render takes a look at our request. It sees that we are requesting /content/this-blogs-stack/.

Render needs some configuration from you to be able to know what that path represents. I have linked Render to a (private) Github repo that contains my site's content. Within that repo, there is a build/ directory, which is what I told Render is my Publish Directory (this is their term for "The relative path of the directory containing built assets to publish."). If your repo has a build system, you can give Render a build command it will run, but I am just pointing it to build/, which contains pre-compiled assets (which I'll expound on below). I also have Auto-Deploy set to Yes, and the Branch Render cares about set to main, so any merge to main will cause Render to re-deploy.

Ultimately, after a "deployment", Render makes available the build/ at /. Render has pulled the build/ directory from the main branch of my provided repo and placed it on a server at /. So, our request is for /content/this-blogs-stack/. By convention, if a file isn't actually requested, a file server will assume you are looking for an index.html file. Render will look for a /content/this-blogs-stack/index.html file (which again, corresponds to build/content/this-blogs-stack/index.html in my Github repo's main branch).

Render sees that this file is available, and serves it! (If you want more detail on what "serving" files means, or more detail on static site hosting, read my article What's a Static Site.)

So, our request is complete at this point:

• We typed https://whyfivetimes.com/content/this-blogs-stack/ and hit enter
• The DNS system did its thing:
  • It took our request over to Porkbun where the whyfivetimes.com domain is registered
  • It saw a pointer to the Render why-five-times.onrender.com domain, and sent our request to the Render servers that accept requests to that domain name
• The Render server at the domain understood that a request for content/this-blogs-stack/ was a request for the build/content/this-blogs-stack/index.html file present in the build/ directory in the main branch of my linked Github repo (based on the fact that Render does "deployments", I am guessing that it actually places a copy of my build/ somewhere on the server, so the files are readily available, rather than requesting them dynamically from Github for each request)

Okay great! That's a request lifecycle. At this point, you may be wondering, how was the build/ directory produced?

Great question. For that, I wrote a simple static site generation (SSG) tool that takes a source directory, with assets and markdown content, processes the markdown into HTML using markdown-it with a few plugins enabled (like emojis and syntax highlighting), and outputs the rendered HTML and static assets (JS, CSS) into a build/ directory. This tool is available at https://github.com/agmazzuckelli/super_simple_ssg, and the README there dives into how it works. I did evaluate several SSG tools, of which Eleventy stood out for its relative simplicity and positive reviews. I didn't look much into Astro, but I heard lots of good things there. Overall, my use case is so simple, I figured it would be fun and a good learning experience to roll my own tool. Writing that was about as easy as learning the conventions of one of these other tools.

When I want to write a new article, I open a fresh branch in my site repo, I make a copy of the article template, update some metadata (like title and published_date), and write the article in Markdown format. When I'm happy with how it looks, I run my SSG against the site repo, which updates the build/ directory in the repo. I commit all of this and open a PR in Github. I take another look through the changes there, and then merge the PR into main. When the merge happens, Render detects it, and does a fresh "deploy" of my site (updating its copy of build/). The new content is then accessible!

That's It?

For now. I want to write more, so it should be easy to write. This setup makes it about as easy as logging in to a blogging site and opening, writing, and posting a new article. I also really enjoy diving into different technologies. Down the road, I'm interested in trying things like HTMX, Svelte, or Web Components. Maybe there will be some fun features I want that will actually require those. I'd likely then need to host a web application / API somewhere, so that'd be a shift as well. Not much really beats a simple static site, if writing is your primary goal.

I will mention that the SSG tool is written in Typescript. It could really be in any language that has a Markdown to HTML conversion package, and my site isn't big enough for generation performance to be a big concern. Javascript has a rich ecosystem of web-focused packages, so it's a good pick for a SSG tool.

I will also mention custom styling (on top of the emoji and syntax highlighting support mentioned above). I created my own styles for the site. I find CSS very interesting, but it certainly can be a place you wind up spending a ton of time. Overall, I hope you like the styles.