So this is a bit of a meta one, but I thought I’d make a post about my hugo work flow.

The target audience of this post is people who have already at dabbled with hugo. This won’t be so much of a guide specifically telling you how to do it, but documents my work flow and can maybe give some people coming from the official doco (where I suggest starting if you just want to know the basics of hugo) ideas about how to actually work with hugo in an easy and efficient manner.

It’s also an opprotunity for me to learn from others and I’d love to hear improvements on how my work flow could be improved.

tl;dr

Since this post is pretty long, here’s a quick tl;dr for anyone who just wants a quick overview:

  1. Attach to tmux session tmux attach-session -t hugo
  2. Branch my git repo git checkout -b postname
  3. Create the hugo project hugo new folder/and/postname/index.md
  4. Start my hugo server docker container
  5. Use nvim in a new tmux window to write the post
  6. Transfer images to the hugo directory using scp
  7. Merge the branch back into main (when writing is finished)
  8. Build the page with hugo and deploy the page with hugo deploy
  9. Test and relax

Getting ready

Before doing anything, I’ll fire up tmux and attach to my tmux session with tmux attach-session -t hugo.

I love using tmux for this because it means I always have a Hugo session sitting there, in the right directories, neovim fired up, Hugo dev server container running, everything all ready to go.

Creating a new branch

First thing I like to do is create a new branch of my hugo git repo. Typically if I’m currently on the main branch I will create and checkout a new branch for whatever post I have in mind, for example git checkout -b 03-a-short-guide-to-publishing-this-post for this post. I will then work there in that branch until I’m ready to publish. At which point I’ll checkout back to main and merge my changes from the devopment branch before publishing live to the site.

Originally I was working in a branch named dev for every post but I’ve since swapped to having branches named based on the post I’m working on. Allowing me to independently work on multiple posts and keep focused on the intent of the branch I am working with.

Creating the project

Image This line was supposed to be an image caption explaining that this is an image of what my environment looks like after I start working on the project. Now instead it’s commentary on how I couldn’t get image captions working with Hugo and this theme and had to resort to left aligned italics instead. 🙃

Next I run hugo new content/posts/00-post-name/index.md - in this case hugo new content/posts/03-a-short-guide-to-publishing-this-post/index.md and we’re good to start writing.

There’s a number of ways to organise projects, but this way I find works well for me. Each project has its own folder in ./content/posts/<post-number>-post-name. The post number at the beginning allows me to easily organise the files chronologically. Also, by keeping posts to their own files, it allows me to keep all data related to the posts (e.g. images) all tidy and organised in that one place, and easier to reference via markdown (for example, the image above is added with ![Image](screenshot.png) - I just need to make sure screenshot.png exists in the same folder as the post and bob’s my uncle.

Editing

To write the post I (and I hope this next part doesn’t shock you) open index.md in my editor 😲

Okay I guess that part isn’t too surprising. But, while I have it open and during the writing process, I also make sure to have my hugo development server running and serving up changes as I go, easily accessible for me in my browser.

It’s nothing fancy but basically this compose file named compose-server.yml sits in my root hugo folder:

version: "3.8"

services:
  hugo-server:
    image: klakegg/hugo:0.101.0
    command: server -D -F -b http://microserver:1313/
    volumes:
      - ".:/src"
    ports:
      - "1313:1313"

Usually it’s already running and ready to go, but if it isn’t I run docker compose -f compose-server.yml up to get it started.

Another bonus of this method is my wife (who happens to be into writing novels as a hobby, and manages website content for a living, so does this kind of thing far better than I) can read my posts, following along and providing feedback along the way.

This is also the step when I add my cover and images (using scp) if the post has any.

Deployment

Once I feel the post is ready, I will merge my changes to main, before doing the build and deploy.

Then comes the build. Originally I was toying with using a docker container to do the build and deploy, but ended up finding less friction with just using the hugo commands locally to build and deploy.

So for anyone already using hugo, this is nothing special, but at this point I pretty much just run (from the hugo directory for my blog) hugo to build and then hugo deploy to push the changes to AWS.

Now I can check the post was pushed successfully (so far, it has never not worked, touch wood) and then sleep well knowing this blog has one more post (which hopefully has helped someone out there in the world).

Final thoughts

So this is my work flow. There’s some bits I like, but also some bits that are still a bit too high friction. Mainly I’d like a more seamless way to add images, right now I do so using scp from within my terminal, not the worst thing in the world but feels a bit clunky so I’ll be thinking about ways to improve that part of the work flow. I think my ideal work flow would allow me just to paste images directly onto this document - but that’s never going to be an option with a static site, so I’ll need to find some kind of compromise.

Feel free to reach out if this helped or if you have any questions (contact are details on my about page). Apologies for not having a comment section here yet, I am still considering my options - if anyone has any good ideas on that front I’d love to hear too!

Anyway, thanks for reading, I hope you maybe learned something and may you have an excellent day kind reader 🙂