how to create a hugo theme

Creating a Hugo theme involves understanding the Hugo static site generator, writing templates using Go templating, and organizing your files correctly. Below is a step-by-step guide to help you create a Hugo theme from scratch.

Step-by-Step Guide to Creating a Hugo Theme

1. Install Hugo

First, make sure you have Hugo installed on your machine. You can download it from the Hugo releases page or use a package manager like brew on macOS:

brew install hugo

2. Create a New Hugo Site

Create a new Hugo site if you don’t already have one:

hugo new site my-hugo-site
cd my-hugo-site

3. Create a New Theme

Within your Hugo site directory, create a new theme:

hugo new theme my-theme

This will create a new theme directory structure inside themes/my-theme.

4. Understand the Theme Directory Structure

Here’s an overview of the essential directories and files:

my-theme/
├── archetypes/
│   └── default.md
├── layouts/
│   ├── _default/
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   ├── partials/
│   │   ├── footer.html
│   │   ├── header.html
│   │   └── head.html
│   └── shortcodes/
├── static/
│   ├── css/
│   ├── js/
│   └── images/
├── theme.toml
└── README.md

5. Create the Base Templates

`layouts/_default/baseof.html`

This is the base template that other templates can extend.

<!DOCTYPE html>
<html lang="en">
<head>
  {{ partial "head.html" . }}
</head>
<body>
  {{ partial "header.html" . }}
  <main>
    {{ block "main" . }}{{ end }}
  </main>
  {{ partial "footer.html" . }}
</body>
</html>

`layouts/_default/single.html`

This template is used for single content pages.

{{ define "main" }}
  <article>
    <h1>{{ .Title }}</h1>
    {{ .Content }}
  </article>
{{ end }}

`layouts/_default/list.html`

This template is used for list pages, like your blog homepage or category pages.

{{ define "main" }}
  <h1>{{ .Title }}</h1>
  <ul>
    {{ range .Pages }}
      <li>
        <a href="{{ .Permalink }}">{{ .Title }}</a>
      </li>
    {{ end }}
  </ul>
{{ end }}

6. Create Partials

`layouts/partials/head.html`

Include common <head> elements.

<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>{{ .Title }}</title>
<link rel="stylesheet" href="{{ "css/styles.css" | relURL }}">

`layouts/partials/header.html`

Add your site header.

<header>
  <nav>
    <ul>
      <li><a href="{{ "/" | relLangURL }}">Home</a></li>
      <!-- Add more links as needed -->
    </ul>
  </nav>
</header>

`layouts/partials/footer.html`

Add your site footer.

<footer>
  <p>&copy; {{ now.Format "2006" }} Your Site Name</p>
</footer>

7. Add Static Assets

Place your CSS, JavaScript, and image files in the static/ directory.

8. Configure Your Theme

Edit the theme.toml file to include metadata about your theme:

name = "my-theme"
license = "MIT"
licenselink = "https://opensource.org/licenses/MIT"
author = "Your Name"
homepage = "https://example.com"

9. Test Your Theme

In the root of your Hugo site, edit config.toml to use your theme:

theme = "my-theme"

Run the Hugo server to test your theme:

hugo server

Open your browser and navigate to http://localhost:1313 to see your theme in action.

10. Iterate and Improve

Continue adding styles, scripts, and content types as needed. Customize your templates and partials to match your design requirements.

Conclusion

Creating a Hugo theme involves setting up a directory structure, writing templates using Go templating, and organizing static assets. By following this guide, you can create a professional and customizable Hugo theme tailored to your needs.