Hugo Blogging

If you have known me for a while, Wordpress used to be my go-to platform for blogging. While Wordpress has some very powerful customization features, I’ve never felt complete control over my content.

Enter Static Site Generation. With Static Site Generation (SSG), I store my posts as “barebone” text files. Whenever I’m ready to publish, these text files get transformed into beautiful HTML pages. Since post files intrinsically don’t contain any UI code, applying different themes to the website is remarkably easy. Most importantly, my post files are extremely portable.

I’ve found Hugo to be the most elegant SSG framework. Sites generated through Hugo can be deployed to GitHub through GitHub Pages. GitHub Pages blogging is free, easy-to-use, and backed by (proper) version control.

Prerequisites

Setup


GitHub Setup

  1. Create a new repository.
  2. Name the repository using the following format: <YOUR_GITHUB_USERNAME>.github.io. For example, andrewmjordan.github.io.

Note: My GitHub username is “AndrewMJordan”, but any capitalization is accepted.

  1. Change any other settings, then press “Create repository”.
  2. Go the repository “Settings”.
  3. Choose “Options” on the left. Find the GitHub Pages settings.
  4. Set the branch to “master”.
  5. Set the folder to “/docs”.

Hugo Project Setup

  1. Clone the GitHub repository.
$ git clone <GITHUB_REPO_URL>

In my case,

$ git clone https://github.com/AndrewMJordan/andrewmjordan.github.io
  1. Open the repository folder. In my case,
$ cd andrewmjordan.github.io
  1. Create a new Hugo site (hereafter, “Hugo project”).
$ hugo new site .
  1. Add a Hugo theme. We will use the Hermit theme since it includes useful example files.
$ git clone https://github.com/Track3/hermit.git themes/hermit
  1. Copy the example files into your project.
$ cp -a themes/hermit/exampleSite/. ./
  1. Edit config.toml.

    • Change the value of “publishDir” to docs.
      • If “publishDir” doesn’t exist, add the following line to the file:

        publishDir = "docs"

      • IMPORTANT: this must appear before all configuration root object ([Author], [params], etc.) sections.

      • Change the value of “baseURL” to your GitHub pages URL.

        baseURL = "https://andrewmjordan.github.io"

  2. Test the site locally.

Run the following:

$ hugo serve --buildDrafts

The --buildDrafts options tells Hugo to include drafts.

Then, browse to the address printed in the output. (It will look something like http://localhost:1313/)

$ hugo serve --buildDrafts
Start building sites …

                   | EN
-------------------+-----
  Pages            | 33
  Paginator pages  |  0
  Non-page files   |  0
  Static files     | 10
  Processed images |  0
  Aliases          |  0
  Sitemaps         |  1
  Cleaned          |  0

Built in 74 ms
Watching for changes in /mnt/c/Users/andrew/temp/my-site/{archetypes,content,data,layouts,static,themes}
Watching for config changes in /mnt/c/Users/andrew/temp/my-site/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
  1. Create a git commit.
$ git add -A
$ git commit -m "Initial commit"
  1. Push to GitHub.
$ git push

Usage

Create New Post

  1. Choose a name for your post. Let’s use welcome as an example.

  2. Run the following:

$ hugo new posts/welcome.md

content/post/welcome.md created

This method is preferred since it generates default front matter for you.

  1. Edit the file at content/posts/welcome.md. Write your post with markdown. When you are ready to publish, change draft: true to draft: false in the front matter.

Deploy Hugo Project

  1. Run the following:
$ hugo

Without any arguments, the command will use the “theme” and “publishDir” from config.toml.

  1. Create a git commit.
$ git add -A
$ git commit -m "Deployed site"
  1. Push to GitHub.
$ git push

Conclusion

Congratulations, your blog is now up-and-running. There are a myriad of ways to proceed from here. Therefore, I’m seperating this series of posts into short, topic-specific modules. That way the reader can choose to read/skip posts at their discretion.


640 Words

2021-02-05 20:54 +0000