I’m looking for the quickest way to start a blog and the easiest blogging tool
to maintain. After looking thru a few of the “Top 10 Static Blogging Tools”
sites, I landed on Hugo. Its written in Go
which makes
it very portable. The tools are available in brew and
port, two of my favorite MacOS package management
tools.
Quickstart
I followed the quick-start guide and installed the tools with brew:
brew install hugo
hugo version
> hugo v0.92.0+extended darwin/amd64 BuildDate=unknown
I decided to use the ‘docs’ directory to publish to on github; for some reason github only offers two options
/ (root)
/docs
It feels cleaner to publish to an output directory.
NOTE: don’t forget to
touch .nojekyll & git add .nojekyll
in the root directory; this will prevent the GitHub Action from trying to run jekyll (This can reduce the build time to a few seconds). As described in this post it must be placed in the document root.
build-site and serve
The instructions call for building and testing the site with the commands:
- to build
hugo -d ./docs
git add docs
- to start a local server on localhost:1313
hugo server
I like to ensure that the commands are run from the correct directory (in this case its the project-root directory). So I rolled these commands into bash scripts:
SWD="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
PROJECT_ROOT="$( dirname "$SWD" )"
DOCS_DIR="docs"
TGT_DIR="${PROJECT_ROOT}/${DOCS_DIR}"
cd "${PROJECT_ROOT}"
hugo -d "${TGT_DIR}"
git add ${DOCS_DIR}
SWD="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
PROJECT_ROOT="$( dirname "$SWD" )"
cd "$PROJECT_ROOT"
hugo server
new-post
The method for starting a new post also requires some memory; you have to invoke the ’new’ sub-command and the content org structure:
hugo new content/posts/<post-name>.md
POST_SLUG="$1"
SWD="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
PROJECT_ROOT="$( dirname "$SWD" )"
NOW=$(date "+%Y-%m-%d")
TGT_POST="content/posts/$NOW-$POST_SLUG.md"
cd "${PROJECT_ROOT}"
hugo new -v "${TGT_POST}"
This script automates the prefix, date and file extention to reduce the barrier for starting new posts. It takes one argument for the base filename. The verbose switch is used to remind you where to find the files.
./bin/new-post hugo-blog
> Content "/Users/nick/src/nckz.github.io/content/posts/2022-01-22-hugo-blog.md" created
Finalize
There are a few other instructions (not listed here) that deal with theme-ing and configuration. The things that caused more time than necessary were the new instructions on linking DNS and setting up HTTPS in GitHub.
From the GitHub Settings->Pages
menu, in the target repository, you can
automatically enter the CNAME in a UI field which will write a file in your
repo at the location that corresponds with your site’s root, e.g.:
cat docs/CNAME
>toughiculties.com
You’ll have to make an A record with one of the IP addresses listed here: Managing a custom domain….
It’s also important to make sure that all configured urls have ‘HTTPS’ i.e. the main configuration file config.toml.
When this is all in order; you’ll have the option to check the ‘Enforce HTTPS’ box which will automatically requisition a certificate from Let’s Encrypt.
This can all take a while (minutes/hours) before the automated checks embedded
in the GitHub Settings->Pages
menu will allow you to proceed. When all
checks are green, the site will be ready to preen.
Additions
Since I moved my blog from a previous setup (GitStrap); I wanted to move the Google Analytics tracker and Disqus comments over too.
Google Analytics
First I copied the existing
site verification html file
to the /docs
directory; this works automatically.
Then I added my ‘property id’ to the
configuration file.
I’m using the Ananke
theme so the instructions for enabling addons can be found her in the
Production section.
I had to add HUGO_ENV=production
to my build command.
The layout is automatically taken up and added on the next build. This can be verified by viewing the ‘Realtime’ stats in Google Analytics.
Disqus Comments
This was an easy addition; just add the shortname to the config as shown in Configure Discuss. The Ananke theme already has these tags builtin to the layout so there is no need to modify the existing layout.
.gitignore
It’s important to know which files are not necessary to track; there seems to
be consensus around the resources/_gen
directory (see
example).
Images
Make a directory ‘images’ under the ‘static’ directory; image refs in the posts
or in the configs will then be made relative to /images
.
Ananke Theme Config
For more configuration tips check out the example config.
Favicon
This was nice and easy; drag’n dropped a PNG onto the favicon.io ‘Image’ page and got my ‘favicon.ico’ file.