How This Website Works

This is a brief manual of how to write and publish pages on this website. It's mainly documentation for my future self, but may also be interesting to people who'd like to set up their own website without content management system (CMS), static site generator (SSG), or blogging platform.

All pages on this website are hand-written HTML documents. HTML is the markup language of the web: understood by all browsers without any preprocessing. You might ask whether it isn't incredibly tedious to write HTML markup, but if you write HTML right, you'll be surprised how readable it can be. Hit Ctrl-u and check out the source code of this page, for example! The boilerplate necessary for each page is stored in a template file, that is, stuff like the viewport meta tag, a link to my style sheet and a hyperlink back to the home page. When I start a new page, I copy that file and replace the title. I got a little script to make my life easier, but it could be done manually just as well.

Creating a new page

To create this post, I ran ./new "How This Website Works", which

  1. created a new year/month/day subdirectory,
  2. copied the template file into this subdirectory as index.html, replacing the title placeholder with the actual title, and
  3. added the link /22/09/27/ with the given title to the home page.

The subdirectory is the final identifier of the page. I intentionally don't use the title for naming the file, as it might change during the writing process or even after publication. Creating a subdirectory instead of just a year-month-day file has the advantage that you can keep additional files for the page (images, style sheets, subpages, etc.) in there. Also, if you write a lot and over several years, thousands of flat files might cause you problems at some point, depending on your file system. As you may have noticed, this is not one of my concerns, unfortunately.

Saving and publishing changes

I keep a versioned history of this website in a private GitHub repository. However, I don't bother with commit messages. I got another small script ./push that stages whatever changes are there and pushes them with the generic message Update. If the repository was public, this push could also automatically publish the website via GitHub Pages, but I prefer to keep my files private and decide when to publish what by linking or not linking from home or some other page. Instead, I deploy the site via Netlify's free starter plan on a domain I bought via Namecheap. Netlify has its own command-line interface, which makes the deployment as simple as netlify deploy.


But what if I want to redesign my whole website, you might interject. With a CMS, I adjust or swap my theme in the GUI. With an SSG, I can edit my templates. Do I have to go through each HTML file manually and replace tags? No, you simply edit your global style sheet. Colors, fonts, spacing, whatever you can imagine, just target the elements on your pages via selectors and style them to your liking. As long as you stick to basic markup for your pages, there should rarely be a need to ever touch them again. If you want to change the navigation between pages, the header or footer of your site, global search and replace is your friend.

That's really all there is to this website, technically.

Update 1: This site now also has an RSS feed, so people can let their feed reader check for updates automatically. It's just an XML file linked from the home page that I maintain manually.

Update 2: I added some tags to the home page. They can be used to filter the list of articles.