Goglides Dev 🌱

Cover image for Create a hugo theme from scratch
Balkrishna Pandey
Balkrishna Pandey

Posted on

Create a hugo theme from scratch

Hugo is a static website generator that allows you to create websites using templates, content files, and configuration files. Unlike traditional CMS platforms, which generate web pages dynamically upon request, Hugo generates all web pages before deployment, resulting in faster page load times and improved security.

Creating a Hugo theme from scratch involves several steps:

  • Before creating a new theme, you must install Hugo on your computer. Hugo is available for all major operating systems which you can download from here.

  • Once Hugo is installed, you can create a new site by running the following command in your terminal:

hugo new site <site-name>
Enter fullscreen mode Exit fullscreen mode

Replace <site-name> with the name of your new site.

For example,

hugo new site ztp.goglides.dev
Enter fullscreen mode Exit fullscreen mode

Output:

Congratulations! Your new Hugo site is created in /Users/bpandey/Documents/workspace/inprogress/antora/ztp.goglides.dev.

Just a few more steps and you're ready to go:

1. Download a theme into the same-named folder.
   Choose a theme from https://themes.gohugo.io/ or
   create your own with the "hugo new theme <THEMENAME>" command.
2. Perhaps you want to add some content. You can add single files
   with "hugo new <SECTIONNAME>/<FILENAME>.<FORMAT>".
3. Start the built-in live server via "hugo server".

Visit https://gohugo.io/ for quickstart guide and full documentation.
Enter fullscreen mode Exit fullscreen mode

It will generate much of files and folder structure

cd ztp.goglides.dev
tree
Enter fullscreen mode Exit fullscreen mode

Output:

.
├── archetypes
│   └── default.md
├── assets
├── config.toml
├── content
├── data
├── layouts
├── public
├── static
└── themes

8 directories, 2 files
Enter fullscreen mode Exit fullscreen mode
  • Here themes directory will be the directory where you will place all the theme files. Inside your theme directory, create a new folder for your theme. For example, if you want to call your theme mytheme, create a folder called mytheme in the themes directory.

  • Inside the mytheme folder, create a new file called theme.toml. This is the configuration file for your theme, where you can set the theme name, author, and other metadata. Here is an example:

name = "My Theme"
description = "A simple Hugo theme"
author = "Your Name"
license = "MIT"
Enter fullscreen mode Exit fullscreen mode
  • Create a new folder called layouts inside the mytheme folder. This is where you will store all the template files for your theme.
  • Create a new folder called partials inside the layouts folder. This is where you will store the reusable partial templates that can be included in other templates.
  • Create a new file called baseof.html inside the layouts folder. This is the base template that all other templates will inherit from. Here is an example:
<!DOCTYPE html>
<html>
<head>
    <title>{{ .Title }}</title>
</head>
<body>
    {{ template "partials/header.html" . }}
    {{ block "main" . }}{{ end }}
    {{ template "partials/footer.html" . }}
</body>
</html>
Enter fullscreen mode Exit fullscreen mode
  • Create a new file called header.html inside the partials folder. This is a reusable partial template for the header section of your site. Here is an example:
<header>
    <h1>{{ .Site.Title }}</h1>
    <nav>
        <ul>
            <li><a href="/">Home</a></li>
            <li><a href="/about/">About</a></li>
            <li><a href="/contact/">Contact</a></li>
        </ul>
    </nav>
</header>
Enter fullscreen mode Exit fullscreen mode
  • Create a new file called footer.html inside the partials folder. This is a reusable partial template for the footer section of your site. Here is an example:
<footer>
    <p>&copy; 2023 MySite</p>
</footer>
Enter fullscreen mode Exit fullscreen mode

Your theme folder should look like this at the end.

Hugo Theme

  • Finally, in your config.toml file, set the theme parameter to the name of your theme (in this case, mytheme):
theme = "mytheme"
Enter fullscreen mode Exit fullscreen mode

That's it! You now have a simple Hugo theme that you can use for your site. You can customize the templates and add more files as needed to build out your theme.

Now try running hugo serve command, you will see output something similar to this,

Start building sites … 
hugo v0.110.0+extended darwin/amd64 BuildDate=unknown
WARN 2023/02/15 10:20:12 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.
WARN 2023/02/15 10:20:12 found no layout file for "HTML" for kind "taxonomy": You should create a template file which matches Hugo Layouts Lookup Rules for this combination.

                   | EN  
-------------------+-----
  Pages            |  4  
  Paginator pages  |  0  
  Non-page files   |  0  
  Static files     |  0  
  Processed images |  0  
  Aliases          |  0  
  Sitemaps         |  1  
  Cleaned          |  0  

Built in 11 ms
Watching for changes in /Users/bpandey/Documents/workspace/inprogress/antora/ztp.goglides.dev/{archetypes,assets,content,data,layouts,static,themes}
Watching for config changes in /Users/bpandey/Documents/workspace/inprogress/antora/ztp.goglides.dev/config.toml
Environment: "development"
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop
Enter fullscreen mode Exit fullscreen mode

and you should able to browse the application at http://localhost:1313/, with your custom theme which looks like this,
Hugo Basic Theme

Top comments (0)