This article is a draft. I’m drafting in public here.
This blog is a repo hosted on Github. I write each post as a Markdown (md) file. I don’t compile, transpile, convert, or do anything else special to those files*. The blog is static and it’s future proof.
As I write this, I realize that I have a few little supporting pieces that tie it together and that I don’t think about much. I’ll talk about those here, but keep in mind, none of them are necessary. You can do this with just a domain name and a set of md files.
I started blogging about 20 years ago. I purchased a VPS from Digital Ocean and installed Linux, Apache, and PHP. Then I installed Dokuwiki. Once it was installed, I could do all my writing in the browser, which is nice. After using it for this long, though, I’ve come across a couple problems with running it for my personal blog. These things are not specific to Dokuwiki and really apply to anything that needs to be installed on my own server.
First, the wiki is still under active development and keeps on top of security updates. That’s a good thing but it means that I need to run software upgrades every few months. On top of that I need to keep the host OS and all of it’s packages updated. But, I’m hesitant to make big host updates because it could break the wiki.
That brings us to my second problem. It has proven difficult to move to a different server. I’ve tried a few times over the years but I’ve never really gotten it to port over to another system. For my most recent try, I fired up a Mac Mini and set it on a small table. I’ve got a nice fiber connection here and I thought it might be time to try hosting the blog right from home. In theory, it should be simple to move, just copy a data directory. But, in practice, it doesn’t work out that way. I would probably need to devote at least a weekend to the project.
The Markdown format has also become ubiquitis amoung technical people and I find myself writing in that style regularly. It makes sense for my blog to be Markdown as well. One of the great things about Markdown is that it’s just text.
For longevity, I’ve noticed that two formats have remained consistant. First, text files have been around as long as I’ve been using computers and I still use them regularly. Second, HTML has been pretty constant since it was created. It gets updates, but the basics have stayed the same and modern browsers can still view very old web pages. I would consider either format to be made to last.
I’ve had joeldare.com registered at Namecheap for many years. Before that my registrar was some other company, I forget their name, and that company closed down and eNom took over their accounts. Both my previous host and Namecheap are eNom resellers, but they bolt a few features on top of the basic eNom offering. I only stayed with eNom for a couple years and then I switched over to Namecheap. I’ve been happy with their service since switching.
Github offers hosting for public and private repos. You can host a special github-pages branch or you can host your root directory. For this blog, I host the root directory. I opend the Settings page on Github and entered my domain name, joeldare.com, into the Custom Hostname field. Github automatically created a tiny CNAME file in my repo. It just contains the domain name, joeldare.com, on a line by itself.
Although I have a paid account, you can currently do all this under their free offering.
This is really the magic part of this whole thing. I added a tiny _config.yml file to my repo. This file just contains the following three lines. It controls the name, title, and url of my home page.
title: "Joel Dare"
name: "Joel Dare"
url: https://joeldare.com
If you leave this file out, your site will still work perfectly fine, but your articles will live by themselves without a site-title and link back to your home page at the top. You’ll still have an article title though.
My home page is just another post in this system and all my links to other articles are maintained manually. It’s simply the index.md file in the repo.
When I link to other pages, I do so without the md extension. Here’s an example link.
[Example Post](example-post)
In that case, Example Post is stored in the example-post.md file and the final URL is https://joeldare.com/example-page.
In order to publish, I simply commit my latest changes to the files in my repo. Here are the exact commands I run.
git add .
git commit -m 'Additional writing'
git push
To make my life just a tiny bit easier, I’ve put those three commands into a deploy.sh file and marked it as executable. That way, I can just run ./deploy.sh and my site will be deployed live within a few minutes.
It may appear that I have a little bit of vendor lock-in with this solution, but I don’t think so. If I ever need to move away from Github I’ve got my plain text files. I can push those to another git provider like BitBucker or GitLab and see if they publish them in a similar way. I could also download a static site generator like Hugo or Jekyl and have that compile my files for me.
</sup> Github does run their version of *Jekyl on my files, but that’s all magic that Github does for me.
Written by Joel Dare on January 20th, 2021.