Creating a Hugo theme from scratch

Hugo can generate the basic structure of a theme, but the command only gives you a skeleton. The useful part is knowing which files Hugo expects and where your templates belong.

Install Hugo

Install Hugo using the official setup guide. Once the hugo command works, create a site and move into its root directory.

Generate a new theme

Hugo does not add a default theme, but it can generate the starting files for one:

hugo new site site-name
cd site-name
hugo new theme theme-name

What Hugo creates

.
└── theme-name
    ├── LICENSE
    ├── archetypes
    │   └── default.md
    ├── layouts
    │   ├── 404.html
    │   ├── _default
    │   │   ├── baseof.html
    │   │   ├── list.html
    │   │   └── single.html
    │   ├── index.html
    │   └── partials
    │       ├── footer.html
    │       ├── head.html
    │       └── header.html
    ├── static
    │   ├── css
    │   └── js
    └── theme.toml

LICENSE

The generated theme uses the MIT licence by default. Change it if that is not the licence you intend to publish under.

archetypes

Archetypes provide the default front matter for hugo new. If the theme expects custom fields, add an archetype for each content type that needs them.

content

The site’s pages and posts live here. This directory belongs to the site rather than the generated theme skeleton.

layouts

These HTML templates turn content into pages. The directory contains the base template, list and single-page layouts, the home page, taxonomy templates, and reusable partials.

static

Files in this directory are copied to the published site as-is. It is a suitable place for CSS, JavaScript, and images that do not need Hugo’s asset processing.

theme.toml

This file describes the theme: its name, licence, description, author, and related metadata.

If the theme will be shared, fill out theme.toml and the licence before publishing it. Those files are easy to forget because they do not affect local rendering.

Add the first page

Use hugo new to create a content file with the archetype’s front matter:

hugo new posts/my-first-post.md

The new site includes a default archetype in the archetypes folder. Edit it before creating many posts if you want every file to start with the same fields.

Build the actual layouts

The generated files are only placeholders. I would begin with baseof.html, then add the shared head, header, and footer partials before working on single.html and list.html. That gives every page a consistent frame early.

Hugo’s documentation covers the template lookup rules, which are worth understanding before the theme grows. Once it builds correctly, the output is static HTML and can be hosted almost anywhere.