Will Murphy's personal home page

One of my goals with creating this blog was to have an easier and more local workflow than I had with wordpress, so here’s a bit more info on that workflow. Every morning (so far!) when I’m ready to make a post, I open VS Code in the directory where my hugo blog is and get to work:

When I have an idea

When I have an idea for a blog post, I just run hugo new posts/my-new-idea.md and press enter. Then I add a few sentences to the file so that I know what I meant to write about when I come back later. Then I commit the draft and git push it up to the AWS CodeCommit repository I’m using. Because the post file has draft: true in the metadata, it won’t show up on the public website yet.

When I want work on a post

When it’s time to get some work done on the blog, I’ll open up the blog folder in VS Code and run hugo list drafts to get an idea of what posts I could finish up and publish. If I’m really not sure what to work on, I’ll run hugo list drafts | xargs wc to see which drafts are getting close to done. I’ll then run hugo server -D to serve a version of the blog that shows drafts on localhost, and start writing. hugo server listens for file changes and redraws the page automatically, so I can immediately see the results of my work.

When I want to troubleshoot something

Especially since I am still learning hugo, I occasionally just break something, or have a simple question like, “how do I put my post’s title on the top of the page.” When this happens, I will often run hugo or hugo --buildDrafts and look at what gets written in ./public in the root of my blog. What ends up there is the exact html, css, etc that will get served from the production website, so looking at it to understand what hugo did or didn’t do is pretty helpful.

Becuase hugo relies pretty heavily on convention over configuration, it can be a bit tricky to learn exactly what it’s doing. A lot of the troubleshooting posts about hugo seem to be people not knowing what the conventions are, so looking at ./public to see what it in fact did is an important tool.

I personally find convention over configuration to be a mixed bag. For example, I don’t have to have a giant config file that lists exactly what subdirectories map to exactly what html partials on render. On the other hand, that map exists, it just happens to be a inside hugo’s source code, so occasionally I’m slowed down when I wish I could look at it.

While writing this, I had an idea for a future post about troubleshooting hugo, so I ran hugo new posts/troubleshooting-hugo.md and added a couple sentences there. That way, in my next session, hugo list drafts will remind me that I have I meant to post about troubleshooting hugo, and maybe I will!

When I want to publish a post

My favorite part about working with hugo is how repeatable and delightful publishing a post is now that I have everything set up. Here’s what I do:

Put draft: false in the front matter of the post file, and set the date: to today.
Update the changelog with a link to the new post
Commit those two changes in the same commit: git commit -m "publish <some post>"
Run hugo server without -D and look to see that everything looks ok. Click the links to make sure they work.
When things look good, run git push

Within maybe one or two minutes, the new post is being served from the production blog, and I can go on with my day. I really love that about hugo.

Till next time, happy learning!
– Will