Intro

Hugo Logo

When I decided to start this site, I thought WordPress was the obvious choice. I’ve used it before for a few projects but every time I revisit WordPress, I am quickly reminded that I just don’t enjoy working in it. There are so many options and plugins and themes that it becomes a bit overwhelming and I just wanted to start writing. Django was certainly an option—I’ve built a number of decent web applications with it over the years and could certainly build a django-based blog but that was also a huge stack of technology to deal with before I could write the first hello world post.

Happily I stumbled upon Hugo via a Youtube rabbit hole. It was markdown-based, fast, simple and scriptable and lends itself to some clever CLI workflows. Exactly what I was going for.

First Impressions

  • Markdown everywhere = good.
  • PaperMod is clean but takes some tweaking to look “less academic.”
  • Git feels natural here; the site is a repo.
  • CLI + scripts give me more control than a CMS ever would.
  • Static site generation so the site is fast and lightweight while still featuring some impressive scripted bits

Editing Options

I’ve tried a bunch of different tools to write and edit posts:

  • Vim: unbeatable for quick edits, regex magic, and staying close to the shell.
  • VS Code: excellent overall, though it still lacks a truly reliable spellchecker.
  • Obsidian: great for note-taking and linking ideas, but with some quirks.
  • Typora: clean interface and live preview, though not much beyond Hugo’s built-in preview.

These days I bounce between VS Code (for structure) and Vim (for quick fixes), always wishing for a universal spellcheck to catch the stray typos. Working in Markdown keeps me close to the writing while hiding the verbosity of HTML and CSS. When I need more control, Goldmark’s settings let me drop into raw HTML without friction.

My workflow is simple: one terminal tab runs hugo server -D, while two browser tabs track the local dev server and the public site. Make a change, see it reflected instantly. Everything lives in git. When it’s time to publish, one script takes it live.

Publishing Workflow

After setup, the main challenge was getting updates live without friction. WordPress gave me gui menus, Hugo gives me a (GoLang) binary. Perfect excuse to write my own tooling. I was able to quickly identify a manual workflow and then build a nice, robust script to automate it. What a lovely experience.

What I ended up with was the following publish script that I run almost daily. It handles cleaning, building, syncing—everything I don’t want to think about.

🔗 View publish-hugo on GitHub

Why not Git hooks or CI? Because I like the flexibility of running this script on any machine, without a network dependency.

The script automates the full Hugo publishing cycle with built-in safety checks. It first makes sure any hugo server process is stopped, then moves into the correct project directory and does a clean rebuild with hugo –cleanDestinationDir. Before pushing anything live, it can snapshot your work in git: if there are uncommitted changes, it shows a concise diff and asks whether you want to commit and push. Even the commit message is auto-built from changed .md files, so you always have a traceable record of what was published.

From there, publish.sh adds several quality-of-life touches. It warns you if you’re about to ship drafts, prompts before doing the destructive rsync –delete, and supports a dry-run mode so you can verify before touching your server. The rsync step itself is simple but effective—mirroring your public/ folder to the remote web root in one shot. And because it’s a Bash script, the UX is colorful and conversational, ending with a celebratory fortune if you have that command installed. In practice, this makes for a deploy process that’s safe, repeatable, and just a little bit fun.

Pre-Press and Sanity Checks

Publishing text isn’t just about writing—it’s about cleaning. In my hugo directory I created a scratch folder and scratch/bin to hold helper scripts and test pages as I create them. It’s a good place to keep site tools and I have a few good ones already.

metaclean

Metaclean is a simple, robust tool for working with images in pre-press workflows. It can scan and strip metadata in a variety of ways that makes it very scriptable.

Check out my 🔗 Metaclean post for the script.

tag-scan

Tag audit is a simple script that reports on category and tags usage in my posts. It helps me to keep my taxonomies straight and to spot typos and outliers and to refresh my memory without looking at each posts’ front matter.

Check out my 🔗 Tag Audit post for the script.

That helps me keep track of my usage of tags and categories in a nice report.

Tips and Tricks

Some CLI tools and habits that keep me sane:

  • find, grep, sed, and awk for batch edits.
  • vim -p to open multiple posts side by side.
  • Running Hugo with --cleanDestinationDir so stale files don’t stick around.
  • Using shortcodes and custom CSS tweaks from my style sheet.

Style playground

I made this page public for fun and interest. Bascially I have a page where I try out each markdown element and made it useful as a glyph board from which I can copy various unicode and emoji symbols. By having a testing ground I can quickly try out CSS changes and see the results in one place. The original markdown also gives me a crib sheet from which I can copy useful snippets when I forget.

Check out my 🔗 Ninjas post for the shenanigans.


Links & References

HTML & CSS References

Hugo Resources

Conclusion

Hugo doesn’t feel like “a CMS.” It feels like a tool that disappears once you wire it into your workflow. With a few scripts and sanity checks, publishing feels like running make.

🧾 View Other Hugo Posts

Have a favorite Hugo trick? Or just a good spellchecker for VS Code?
📬 feedback@adminjitsu.com — always happy to swap notes.