Hugo Static Site Generator Blank Starter Theme

I’m in the process of converting my WordPress site into a static site compiled from markdown files using the Hugo static site generator. For this task, I created a blank Hugo starter theme that uses Webpack and optional webpack-plugin-serve for UI development build live reload.

screenshot

Source Code

Pre-requisites

You will need Git and NodeJS with NPM installed.

Installation

For example, if your Hugo website is in the www folder.

cd www

git init

git submodule add https://github.com/jimfrenette/hugo-starter.git themes/starter

If you get an error, git submodule add https://github.com/jimfrenette/hugo-starter.git themes/starter 'www/themes/starter' already exists in the index. Unstage it using git rm --cached themes/starter.

Webpack Build

Install node modules.

cd www/themes/starter

npm i

Build the UI with npm run build. CSS and JavaScript files will be output into the starter themes dist folder. e.g.,

cd www/themes/starter

npm run build

Reload the webpage with cache disabled to see the any UI build changes. An easy way to do this is with browser dev tools open and it’s cache disabled setting active.

Optional Webpack Live Reload Dev Server

Install the webpack-plugin-serve module using npm.

cd www/themes/starter

npm i webpack-plugin-serve -D

Provided you have generated your Hugo website with the hugo command. By default, the generated html files are output into the ./public folder. e.g., www/public. If you have customized the output directory in the site config publishDir property, update the respective webpack/dev.config.js webpack-plugin-serve static path. e.g.,

dev.config.js

const baseConfig = require('./base.config.js');
const merge = require('webpack-merge');
const { WebpackPluginServe: Serve } = require('webpack-plugin-serve');

const serve = new Serve({
  host: 'localhost',
  static: ['../../public/'],
  open: true,
  liveReload: true
});

module.exports = merge(baseConfig, {
  mode: 'development',  
  devtool: 'eval-source-map',
  entry: {
    app: ['webpack-plugin-serve/client']
  },
  plugins: [
    serve
  ],
  watch: true
});

When you’re ready to develop your theme CSS and JavaScript, run the npm run dev command. This will launch the webpack development server, with watch enabled to build the css and javascrpt as changes are saved to the src. Live reload is also enabled so the changes are immediately rendered in the web browser.

cd www/themes/starter
    
npm run dev

When you’re ready to build without using the Webpack development server, perform the standard production build.

cd www/themes/starter
    
npm run build