🚀 Hugo + Tailwind + NPM: A Guide to Static Site Domination

So I decided to build a static site with Hugo and flex my tech muscles. Of course I was lazy and used other tutorials, themes, and piggy-backed off AI, but who hasn’t these day!? I mean really. Anywho, this is my journey in getting Hugo up for this page, installing the theme, getting my local environment in just lip-smacking good condition to zoom through building out content like aa tiktok start who said that one wrong thing and now can’t get 1000 views.

What we will cover:

• Installing Hugo (extended version, obviously)
• Adding a theme using Hugo Modules (why it’s weird at first)
• Converting YAML configs to TOML (because we like order)
• Installing & using NVM for Node.js (because Tailwind needs Node)
• Running Hugo NPM commands & updating dependencies
• Setting up TailwindCSS for styling
• Challenges & lessons learned
• Future plans (Vue integration and beyond!)

🛠 1. Installing Hugo

First, install Hugo Extended, since it includes support for Sass and other necessary features.

Installation Commands:

• macOS (Homebrew):

  brew install hugo
  

• Linux (Deb-Based):

  # Fetch the latest Hugo version
  HUGO_VERSION=$(curl -s https://api.github.com/repos/gohugoio/hugo/releases/latest | grep -Po '"tag_name": "\K.*?(?=")')
  
  # Download the Hugo Extended DEB package
  wget "https://github.com/gohugoio/hugo/releases/download/${HUGO_VERSION}/hugo_extended_${HUGO_VERSION}_Linux-64bit.deb"
  
  # Install the package
  sudo dpkg -i "hugo_extended_${HUGO_VERSION}_Linux-64bit.deb"
  

• Verify installation:

  hugo version
  

Ensure that Git and Go are installed as well, since Hugo Modules require them. If hugo mod init fails silently, you probably need Go.

🎨 2. Adding a Theme Using Hugo Modules

Older guides might suggest manually copying themes or using Git submodules, but we’re using Hugo Modules like real devs. Here’s how:

1. Initialize Hugo Modules:

   hugo mod init github.com/yourname/sitename
   

2. Modify hugo.toml to import the theme:

   [module]
     [[module.imports]]
       path = "github.com/yihui/hugo-xmin"
   

3. Enable the theme:

   theme = ["hugo-xmin"]
   

Run hugo server to test if everything is working. If you see module-related errors, ensure you initialized Hugo Modules properly and have an internet connection.

🔄 3. Converting YAML to TOML (Because We Like Order)

If your theme’s config is in YAML but you prefer TOML, convert manually or use an online converter. I used this to convert the example config from fluidity’s example site.

Example conversion:

• YAML:

  title: "My Site"
  theme: "hugo-xmin"
  

• TOML:

  title = "My Site"
  theme = "hugo-xmin"
  

YAML can be finicky with indentation, so I prefer TOML’s explicit key-value pairs. I used to me team YAML, but over the years, the difference between all the parsers and other funkiness has pushed me toward toml.

📦 4. Setting Up NVM & Installing Node.js (Because Tailwind Needs It), and I have a new machine

So this article is about Hugo, a go tool. I figured myself it wouldn’t mention much else other than some vanilla JS, HTML, and CSS, but to my initial surprise, we need node.js because the theme I chose is using TailwindCSS. That requires the tailwindcss cli. For me, anytime I am doing node development on a unix-like machine, I want to use NVM (Node Version Manager) to manage Node versions easily. It makes moving between environments, versions, and etc so easy. Also, it has saved me from wrecking my system install more than once.

Install NVM:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash

Install Node.js:

nvm install --lts
nvm use --lts

📜 5. Running Hugo NPM Commands & Updating Dependencies

Our theme is using node tools, so we run

hugo mode npm pack && npm update

🎨 6. Installing TailwindCSS for Styling

Install Tailwind:

npm install -D tailwindcss

🔥 7. Challenges & Lessons Learned

• Hugo Modules are tricky at first: Ensure you initialize properly (hugo mod init) and install Go.
• Config formats can be annoying: If you’re switching to TOML, convert carefully.
• Node setup varies: Always check version compatibility (Hugo, Node, Tailwind).
• NPM scripts make life easier: Automate Hugo + Tailwind tasks together.

🔮 8. Future Plans (Going Beyond Static)

• Integrating Vue.js for dynamic components (comments, widgets, etc.)
• Experimenting with modular static content in Hugo
• Custom JavaScript enhancements

If you found this guide helpful, drop a comment and let me know what challenges you faced while setting up your Hugo project! 🚀