Create an Overpowered Hugo Blog (as an WordPress Alternative)

Discover the power of blogging with Hugo! Explore a WordPress alternative offering ease and efficiency. Learn to set up Hugo, leverage GitHub Actions for automation, and utilize Forestry as a CMS. Elevate your blog with Hugo’s simplicity and GitHub’s power.

Create an Overpowered Hugo blog (as an WordPress Alternative)

A developer without a blog is like a fisherman without their fishing rod. While it is possible to fish with just a thread & a hook, the rod makes life much easier for the fishermen. In that context, Dan Bader summed it up well in his article — 3 Reasons Why You Need a Programming Blog.

But, if you’ve read some of my previous articles, you would know choosing the right tools to blog is no easy task. I wrote about such a dilemma I was in earlier. Here’s the article — Medium vs Static Site Generators — A Computer Vision Engineer’s Dilemma. Since publishing that article I had time to experiment with existing blogging tools. And I reviewed each of them. You can read the review at — A Review of Some of the Most Popular Static Site Generators.

Suffice to say, Static Sites Generators did rescue me out of my dilemma.

Static sites also come with the added benefit of never having to worry about server maintenance & security updates. They’re a much better alternative to Wordpress. Besides, they cost almost nothing to produce. You could spend some cash maintaining it, but the financial costs will never be above a few bucks.

So, in this article, I’ll show how you can set up a blog with Hugo. The blog will have a CMS, will update itself & some more OP super powers to add along. So then, without further adieu, let’s dive into setting it up as a Wordpress alternative.

But do note, having some prior programming knowledge can be a bonus point but is not a prerequisite. You can follow along with the instructions suggested in this article & you’ll be fine.

Prerequisite Tools

The star of our article is Hugo. This piece of software is without a doubt one of the easiest to use Static Site Generator available.

Besides Hugo, we’ll also need a GitHub account to host the articles & other tools as well. One of those tools include GitHub Actions. Of the many community-maintained GitHub Actions, we’ll be using a couple of them.

But no blog can be a Wordpress alternative without a Content Management System (CMS). So, to deliver onto our CMS needs, we’ll use the services from Forestry.

And at last, we’ll use Netlify services to deliver the generated static content. They use a global Content Delivery Network (CDN) to deliver the content to our audiences.

Optionally, we could use Google Analytics (GA) for tracking needs. But if you’re a privacy concerned citizen, use Cloudflare Analytics instead.

So, to sum up, here’s the list of all the necessary tools & services we’ll be using:

So, that said, ensure you’re set up with all the tools mentioned above & then we can get started.

Using Hugo (With All Its Glory)

As mentioned earlier, Hugo is without a doubt one of the easiest Static Site Generators available to use. The fact that Hugo has 50K+ stargazers shows how useful it is!

So, without wasting any more time, let’s dive into seeing how to use Hugo.

Installing Hugo

First things first, is to install Hugo on your local machine. Unlike other Static Site Generators Hugo has no dependency! But generators like Pelican, Gatsby and/or Jekyll needs a local Python/Ruby runtime or a JavaScript environment. With Hugo, all you need is the Hugo binary & you’re good to go.

The “ installation” procedure is also pretty simple. You need to add the binary to system PATH & invoke the hugo command from anywhere in the Terminal.

Do note, editing each Operating System’s PATH is quite different. Hence, do take a thorough look at the official installation docs.

Now ensure you installed Hugo by running the hugo version command on your CLI. If everything works fine, you should see a similar output.

Output of “hugo version” Command

Creating Your Site

I must say, installing Hugo while easy, it isn’t the most fun part of the whole process. So, let’s get started with the fun parts.

You can generate a skeleton site (which we’ll build upon soon) with the hugo new site . command. Notice the . ( dot) at the end of the command? It tells Hugo to generate the skeleton site in the current directory.

The command generates a simple set of files & folders. Each of them serves a specific purpose for Hugo. Here’s what the directory structure looks like after generating them.

Hugo Directory Structure

There’s more to what Hugo generates as a skeleton site than what I can discuss in one blog. For more info, do take a brief look at the documentation on Hugo’s project directory structure.

Without delving into the details of the directory structure, let’s keep things minimal. That way, there’ll be room for further personalization. And you can start delivering content at the earliest as well.

Creating Content (The Actual Fun Stuff!)

As mentioned earlier using Hugo is drop-dead easy. Yet, any given Hugo project can be as complicated as it needs to be. But regardless, you can start writing content right away, all you now need is;

It’s that simple!

Hugo boasts of some 300+ beautiful community maintained themes. You can download a theme to your site’s theme directory & Hugo will use it to generate the contents of your site. And the easiest way to install a theme is to use ” Git Submodules “. That way you can ensure the themes are updated as & when the theme authors pushes a commit to its repository.

Installing themes is also very easy. Running the git submodule add <DOWNLOAD-LINK> themes/<THEME-NAME> --depth=1 command is enough.

For SEO needs, you might also need site metadata. And Hugo takes care of it out-of-the-box. You’ve to configure Hugo with a config.yml file. And in that file you include the necessary details for the metadata. Hugo uses those values to populate the metadata of your site.

And to get a general feel of what a config.yml file looks like, here’s an example;

Example Hugo Config File

Do note, configuring the config.yml isn’t limited to what I mentioned here. Based on the theme you’re using, you might/mightn’t have to extend on it.

And at last, the content directory where you store the Markdown files for your articles. You can organize your Markdown content into subdirectories for easier maintenance & organization. For example, here’s how mine looks.

Example Hugo Contents Directory Structure

The Content Organization section of the docs has more details on the topic. Do check it out for more information.

And with that information, you can start creating content right away.

Be sure to store all the articles in Markdown format under the content directory. And if you’re not familiar with Markdown, check out Markdown Guide. Else read ahead to figure out how to use the Forestry CMS.

Now that you’ve started creating content, it’s time for your audience to read them! And the next section is about delivering the content to our audiences..

Deploying the Blog

Unlike Wordpress sites, static sites don’t need a hosting provider (or a server). This alleviates the surface area of potential security & maintenance mishaps. But without a server to host the content how do we deliver them to our audience?

This is where Netlify’s services come handy. They’ll deliver our static content over their global CDN. And their free tier services also come with some nifty goodies. Some of those extra goodies include a domain, a build platform & many more. But for reasons mentioned later, we won’t use all their services.

So, ensure you’ve created a new repo to host your site contents & a Netlify account to start with. You’ll need to perform a one-time operation on the Netlify dashboard to create a new site. Refer to the Netlify docs to know the exact process to do so.

Then push your fresh new site to the GitHub repo, you created. And that should trigger a Netlify build operation. You can now view your website at an URL provided by Netlify ( you can change it though 😉).

Now each time you write a new article or push some aesthetic changes to your site, Netlify will trigger a build. While it works & is fine for most users, there are certain downsides. One of them is the slow & unoptimized build timings ( often taking over 2mins to complete the build). And considering Netlify provides only 300 minutes of build per month, it won’t be long before you run out of it.

Besides, that way you’re not utilizing Hugo’s full potential. Which is why we’ll use some GitHub Actions instead. With it, we’ll deploy our site & automate some monotonous tasks as well!

The next section delves deeper into why & how we can achieve such a feat.

Setting Up Automation & a CMS Backend

Creating & deploying the site was easy & fun. But it doesn’t last long (saying from personal experience). More so, when you add the theme as a submodule. You can expect frequent updates for it.

But thanks to GitHub’s Dependabot, we can keep our theme(s) updated at all times.

There’s also the need for a Content Management System (CMS). What good is a Wordpress Alternative, without a CMS, right? And we should also delegate the build process to GitHub Actions instead of Netlify. This is a more efficient way to deploy & maintain our site.

So that said, let’s list out the remaining features we need to work on & start working on them one-by-one.

GitHub’s Dependabot integration came as a godsend. Because of it, keeping project dependencies up-to-date has never been easier. And guess what? Dependabot can take care of Git Submodules as well! Which means your themes will stay updated as soon as its author pushes some changes to it.

And to configure Dependabot, you need a specific config file for it. This specific file named dependabot.yml stays under the .github directory ( create it if it doesn’t exist yet).

And this is how it should look like:

Dependabot Configurations for GitHub Actions & Submodules

With Dependabot configured, it’ll now look for updates every day at 0600 Hours UTC. And if there’s any, it’ll then open a PR with respective labels for GitHub Actions & Git Submodules each.

But that’s pretty much the tip of the iceberg for Dependabot configuration. You can find detailed Dependabot Configuration Options in the official docs.

With Dependabot set up, you no longer have to worry about manual update & maintenance tasks.

Setting Up Forestry as a CMS Backend

No static blog can become a true Wordpress alternative without a CMS. And that’s what makes Wordpress attractive to most users without any technical prowess. And as such, some users might not be comfortable writing their content in Markdown. For them a web-based Rich Text Format environment is what works best.

Hence, we’ll be using Forestry’s backend CMS services. There are alternatives like Contentful (one of the most popular one) & Netlify CMS. But, from personal experience I found Forestry to be the most easy to setup & configure.

The things you can do with Hugo & Forestry is beyond the scope of this article. I could write another full-blown article on this topic alone. So, keeping this article rather short & act as a guide for interested readers, here’s a gist of how to set up Forestry.

  1. Ensure you’ve Forestry account & your site is “added” to their services.
  2. Configure the settings of the CMS from the Admin panel.
  3. Login to your site’s Admin panel by navigating to <YOUR-SITE-URL/admin> & start writing your content in Rich Text (you can write in Markdown as well if you prefer).

Forestry has a guide to set up their CMS with Hugo. Do check it out as well!

Automation & Delegating Build Task to GitHub

While there’s nothing wrong in using Netlify to build the site, it has some limitations. A major one being, it’s slow & unoptimized build times (it took over 2mins for my site to build). And with Netlify’s limited 300 build mins per month, it won’t take long before the free quota is used up.

So, to make the most out of Hugo’s potential, you should use GitHub Actions. With it, you can build your site in <1 mins ( usually takes 20–40 secs on average for mine).

Besides, compared to Netlify, GitHub provides 2000 build mins per month! So, coupled with less build times & a huge build mins quota, you won’t have to worry about builds not triggering 😊.

Also, having all tools under one roof makes maintenance much easier to handle. So, let’s peruse through what we need to do automate some of the build tasks;

  1. First thing first is to ensure you’ve a netlify.toml config file under the root directory. The Netlify GitHub Action will use it to deploy the website to Netlify’s CDN. The file usually looks something like the following;

Example Netlify Configurations

There are more details about the file in the Netlify Config file documentations.

2. To automate some more monotonous tasks, add a build.yml workflow file. Place it under the .github directory. And add the following content to the build.yml file.

Automated Netlify Build & Deployment with GitHub Actions

This file instructs GitHub Actions to use two workflows for deployment tasks. It’ll set up Hugo, generate the static content & deploy it to Netlify. Further, it’s triggered on every push & PR event.

4. And finally, the best piece of automation fun. Automating PR merges opened by Dependabot.

Remember the automerge labels in the Dependabot config file? This is where they come handy. We’ll use [pascalgn/automerge-action](https://github.com/pascalgn/automerge-action) to merge any Pull Requests with the label automerge. No need for manual intervention.

And guess what? Dependabot is also configured to update every PR it opens with that label! 😆

And thanks to all the automation features, you no longer have to even open the repository ever again! Automation FTW indeed! 🤣

Final Words

Phew, that was quite a long read for a tutorial! And if you read it till the end, then thanks for being thorough with it, much appreciated.

You might’ve also noticed, the article isn’t as comprehensive. Yet it touches upon all the optimal techniques & tools used to maintain a programming blog. So, I hope the information I shared through this article was enough to get you started with your blog as well! If you do so, reach out to me & say “ Hi! Here’s my blog” over social media and/or email. And I might give away a shoutout for you.

Besides, my blog is open-sourced! ❤ So, if you stumble across a roadblock, check out how I maintain mine. Or, feel free to open an Issue/ Discussion thread.

That said, I look forward to how you use Hugo to share your amazing content with the rest of the world!

Originally published at https://jarmos.netlify.app on February 21, 2021.