How I Use Github as a CMS

There are many blogging and wiki options out there, and there are many factors that go into the decision to use one over another. I’ve used WordPress, in both its open source and hosted versions, and I’ve hand-crafted HTML and CSS when that’s what the project called for. I make no claims to know what the one-and-only blogging solution is, because I don’t think that exists.

My Stack

What I’m looking for is:

• Markdown source;
• Static site generator;
• Simple pipeline;
• No-frills non-comercial hosting.

I get that with a combination of Obsidian, VS Code, Hugo and GitHub Pages. I also want my own domain, but that’s not necessary for many cases, in particular FOSS projects, so I won’t go into it here.

Writing in Markdown

Markdown is an open, simple, human-readable, plaintext markup language. Using simple syntax like number signs, asterisks and brackets, one can format documents in a very light way. The plaintext format also makes them portable.

This format is popular for technical documentation and in social media. It’s supported by GitHub, GitLab, Pandoc (which I’ve used for a project before), Reddit, Discord, Lemmy, Matrix, etc. You’re very likely to have used it, even if you didn’t know it.

Since it’s plaintext, any editor works, but I like either Obsidian, a full-featured and extendable note-taking app, or Visual Studio Code, a code-focused text editor turned IDE. Using either of these tools, I can share my notes and post source files across devices.

Generating a Website with Hugo

Hugo is so cool and trendy that it calls for a rocket emoji. Here: 🚀

Let’s back up a bit. I’m writing a blog, not an e-commerce site. I don’t want comments, likes, votes, shopping carts, favorites, user accounts or anything like that. That makes this a static website - it only shows content as-is and doesn’t expect or need user input. That means there’s no need for a database or any backend logic to speak of. All I need is a set of HTML, CSS, JavaScript and maybe image files, so I use a static site generator.

Hugo is written in Go, which makes it cool, and it supports a broad array of themes, because it’s trendy. By running it in the command line, I can create content files with basic front matter and then generate the website and run it in a local server.

Its Markdown rendering, configuration, extendability, and themes are both friendly and complex enough to create pleasing, beautiful, functional and accessible websites - including supporting my extra requirement for multilingual content.

Hosting With GitHub Pages

OK, let’s get this show on the road.

git checkout -b cms
git add content/posts/how-i-use-github-as-a-cms.md
git commit -m "First draft about GitHub."
git push

Pushing the source for this post to a remote repository

GitHub Pages is a service for hosting pages provided by GitHub. Sensible naming aside, for non-comercial uses and with a few technical limitations, GitHub will take the contents of a public repository and host that as a static website. It really is just about as simple as that. GitLab and Codeberg will do the same for you, using equally simple naming. GitLab doesn’t seem to have a friendly landing page for this and instead offers serious documentation, but that’s neither here nor there - you’re most likely going to chose the service where you already have your code, I happen to use GitHub more.

When I push my static site to main, it’s almost instantly served by GitHub with the new content. By having it on there, I get portability, reliability, access to the source from different devices and from anywhere in the world and even options for collaboration, because that’s really what Git is all about.

The CMS Part

But I promised you a Content Management System, didn’t I? A website, an app, something like that, not command line tools.

Well, here it is:

GitHub iOS app

And here:

GitHub website on desktop

Of course, app and web editing a CMS do not make. If publishing a new blog post requires access to command line tools to generate the static pages, and you need to pick up a laptop to make any minor edit, we’ve proved nothing, right?

This is where the pipeline comes in. I have an aversion to reinventing wheels, so I went looking for what I needed and adapted that to my needs. The Hugo team has their own documentation, but since I’m using GitHub’s free service and don’t want the source files to be public - just the generated static site - I found this post from Finisky Garden very helpful. Notice the .github.io that suggests this is hosted on GitHub Pages.

With that as a starting point, here’s my workflow:

1. Create a new post Markdown file on whatever device I happen to be on;
2. Push that to a new branch of my private source repo;
3. At some point, generate the site locally, to check everything worked as I intended it to;
4. Continue writing and editing;
5. Translate the original English post into Portuguese;
6. Merge to main;
7. The pipeline generates the new version of the site and pushes it to the public repo;
8. Share my latest mildly interesting blog post with people;
9. Work through any necessary post-publication editing and push to main again to update.

OK, I really can’t compete with WordPress, but I like it.

Would I Recommend This?

This stack and workflow obviously doesn’t fit all the criteria for a CMS. I haven’t even discussed images, even though that’s not a particularly hard topic to handle with Hugo. I think I’ve made a good case for some of the advantages and I’ve been very open about the main disadvantage: if you want something dynamic, this is not what you’re looking for.

Perhaps the most important question is “is this setup easy to use for most people?” No, of course not. As a software developer, I can extoll the superiority of plaintext and Git all day long, but What You See Is What You Get is popular for a reason. That being said, if all you need to do is make occasional changes to a simple website, most lay people will be able to learn the basics of GitHub. If the infrastructure is there, it really will feel a lot like WordPress.

This approach works for me, because I find the technical process fun. Why else would I write a post about it? If this is what “fun” means to you, I hope coming along for the ride was pleasant. Regardless, go have some fun.

Merging this post to publish it