Hugo Theme Starter

Hugo Theme Starter is a GitHub template for creating new Hugo themes with Vite, a modern front-end build tool that packages source CSS and JavaScript into the static directory and supports a real-time editing workflow with Hugo's built-in server.

What is Hugo Theme Starter?

Hugo Theme Starter is a boilerplate repository that provides a starting point for developing themes for the Hugo static site generator. It accepts your custom CSS and JavaScript source files located in the src directory and uses Vite to bundle them into the static directory when you run npm run build. The template was created by misitebao and is published on GitHub, where it uses the "Use this template" button to generate new project repositories based on its file structure.

Key Features

• Vite build integration — Instead of relying on Hugo's own asset pipeline, the template uses Vite to compile CSS and JS from the src folder into the static folder, giving theme developers access to modern JavaScript tooling.
• Watch mode for live development — The npm run build:watch command watches source files and automatically repackages them into static whenever you edit, allowing you to preview changes in real time.
• Example site included — An exampleSite directory ships with the template so you can run cd exampleSite && hugo serve to test the theme in a genuine Hugo site context.
• One-click repository generation — By clicking "Use this template" on the GitHub page, you create your own copy of the theme scaffold with all files and directories preserved.
• Open-source license — The repository displays a GitHub license badge and is listed on Awesome Hugo, indicating it is freely available for community use and modification.

Who is it for?

• Hugo theme developers who want to build themes using Vite rather than Hugo's built-in asset pipeline and need a preconfigured starting structure.
• Website creators making custom themes who need a local development loop with live reload via build:watch and hugo serve to iterate on design and functionality.
• Developers new to Hugo who want a guided scaffold that includes documented npm commands and an example site to learn theme development without configuring Vite themselves.

What can you do with Hugo Theme Starter?

• Scaffold a theme project: Generate a new repository with the GitHub template, install dependencies with npm install, and run npm run build to produce static assets ready for Hugo.
• Develop with automatic updates: Run npm run build:watch while serving the example site with hugo serve to see CSS and JavaScript changes reflected in the browser without manual rebuilds.
• Preview and test the theme: Use the included exampleSite to run a Hugo server locally, verify templates, and check that the theme works in a full Hugo installation.

How does Hugo Theme Starter work?

The workflow starts by clicking the "Use this template" button on GitHub to create a personal copy of the repository. After cloning, you run npm install to fetch dependencies, then npm run build bundles the source files from src into static. For ongoing development, you run npm run build:watch in one terminal and cd exampleSite && hugo serve in another, so every saved change to your CSS or JS is instantly rebuilt and served locally.