- Hugo is a static site generator that read content files written in Markdown (.md), applies layouts and templates from themes or custom code , compiles everything into static HTML ,CSS and JS files.
Overview
A typical Hugo project has this structure:
my-hugo-site/
├── archetypes/
├── content/
├── layouts/
├── static/
├── themes/
├── public/
└── config.toml
Archetypes
The archetypes/ folder contains template files that Hugo uses when creating new content.
When you create new content using Hugo’s command line tool, these templates provide the starting structure for your new pages or posts.
Example: archetypes/default.md:
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
---
Your content goes here.
When you run a command like hugo new posts/my-post.md, Hugo uses the templates in the archetypes/ directory to populate the front matter of the new file.
Content
The content/ folder is where all your website’s written content lives.
This contains Markdown (.md) files that hold the actual text and information displayed on your website. You can organise these files into subfolders to create the structure of your site.
Example structure:
content/
├── posts/
│ ├── first-post.md
│ └── second-post.md
└── about/
└── index.md
Each content file typically begins with “front matter” - a section at the top between --- marks that contains metadata about the page such as:
Example content file content/posts/first-post.md:
---
title: "Hugo explainer"
date: 2023-04-25
draft: false
tags: ["hugo", "web development"]
---
Hello world!
Layouts
The layouts/ folder contains HTML templates that define how your content is displayed.
These templates determine the appearance and structure of your website. They convert your Markdown content into properly formatted HTML pages.
Common layout files:
layouts/
├── _default/
│ ├── single.html (template for individual pages)
│ └── list.html (template for list pages like blog indexes)
├── partials/
│ ├── header.html
│ └── footer.html
└── index.html (template for the homepage)
The templates use Go’s templating syntax to insert your content into HTML structures.
When you use a theme in Hugo, many of these layout files are provided by the theme itself. You don’t have to create them manually unless you want to customize them. The theme will supply default templates, and you can override specific files in your project’s layouts/ folder if needed (for example, to customise the homepage layout or create a custom post template).
Static
The static/ folder contains files that don’t need to be processed by Hugo.
Files placed here are copied directly to your finished website without any changes. This is where you put images, CSS files, JavaScript files, fonts, and other assets.
Themes
The themes/ folder contains downloaded or custom themes for your Hugo site.
Themes provide pre-made designs and layouts for your site, saving you from building everything from scratch.
The theme I used is PaperMod, which offers excellent extensibility, customisability, and a wide range of configuration options.
You activate a theme in your configuration file.
Hugo first looks for templates in your project’s layouts/ folder, and if not found, it uses the ones from the active theme.
Public
The public/ folder contains your finished website after Hugo processes everything.
What it does: This is the complete, ready-to-deploy version of your website. It’s generated automatically when you run the build command (hugo without parameters).
Note: You should not edit files in this folder directly since they get overwritten every time you rebuild your site.
Config File
The config.toml file (or config.yaml/config.json) contains your site’s global settings.
This configuration file defines site-wide settings and parameters used throughout your website
baseURL = "https://harunfarah.com/"
languageCode = "en-uk"
title = "Harun Farah"
theme = "PaperMod"
[params]
description = "A personal site built with Hugo and the PaperMod theme"
author = "Harun Farah"
Getting Started
To create a new Hugo site with this structure:
- Install Hugo on your computer
brew install hugo - Run:
hugo new site my-website - Change into that directory:
cd my-website - Add a theme (e.g. PaperMod instructions in repo) or create your own layouts
- Create content:
hugo new posts/PanamaPapers.md - Preview your site locally:
hugo server - Build your site for production:
hugo
When you run hugo server, Hugo starts a local development server , automatically rebuilding the site and refreshing the browser whenever you save changes. useful for quick iteration while working on content, layout, or styling.
After you’re happy with your site, running hugo generates the final static HTML, CSS, and JS files inside the public/ folder. These files can be deployed to any static hosting provider.
For this project, I used Netlify, which provides free hosting with built-in CI/CD. Once connected to your GitHub repo, Netlify automatically rebuilds and redeploys your site every time you push changes, making updates automatic, and now you can just add blog posts and updates.
Other Considerations
Hugo is an excellent choice for building brochure sites, personal or blog sites, especially when speed, simplicity, and control are key priorities. Here’s why it worked well for this project:
- No Backend Required: Hugo generates a fully static site, so there’s no need to maintain or secure a backend.
- Security: Since the output is static HTML, it’s more secure by default. There’s nothing dynamic for attackers to exploit.
- Performance: Hugo is incredibly fast, generating sites almost instantly, even with large content.
- Simplicity: The file structure is simple to understand. Content is written in Markdown, and layouts are defined in HTML.
- Version Control Friendly: The entire site, including content, layouts, and configuration, is stored in a Git repository, making it easy to track and collaborate on.
- Perfect for Static Hosting: Platforms like Netlify make deployment seamless, with built-in CI/CD that automatically rebuilds and redeploys the site on every change.
- Extensible without Overhead: You can start with a theme like PaperMod and override or customize layouts as needed without diving deep into the internals.
Overall, Hugo strikes a balance between flexibility and simplicity, making it ideal for developers who want control over their site without the complexity of a full CMS or backend stack.