A Guide to Using Hugo in 2024 and 2025

Creating a website requires a huge time investment. You have to plan for the financial cost of developing, maintaining, and hosting it. If you’re developing it yourself, you need to have significant technical knowledge.

However, not all websites require some complicated architecture or costly resources to run. Sites like blogs, portfolios, company websites, magazines, documentation sites, etc. can be made cheaply and fairly hassle-free using static site generators.

Static site generators

A static site generator or SSG is a build tool that produces static sites.

These sites have pages that are built beforehand and do not change often between user visits. An SSG usually takes templates and adds supplied data to them to create the HTML pages. The pre-rendered pages are then hosted where users can access them. This is unlike dynamic sites where a page is built when a user requests it.

SSGs simplify site development. In some cases, creating a site with an SSG is achieved in only a few steps and a very short period. SSGs are great tools for new developers and those with limited experience who'd like to make sites without much hassle.

Many SSGs are resource-rich and provide a wide range of site themes, common utilities like comments and hosting integration, etc. Some other benefits of SSGs are tied to the static sites they produce.

Static sites involve a lot fewer moving parts and are easier to build, secure, and maintain. They are fast since pages are already pre-rendered and are served as is. Scaling static sites is easier compared to other sites with more complex infrastructures.

HUGO

Hugo is an SSG and framework written in Go. It uses Go templates for its layouts. A key advantage that sets it apart from other SSGs is how fast it builds pages.

It provides amazing content management, is available on multiple OS platforms, supports taxonomies, offers tables of contents generation, supports pretty URLs, and can be hosted virtually anywhere. In addition to these features, it provides live reload during development, supports different content type options, and has word count and minutes-to-read functionalities. These are just a sampling of the many features Hugo has to offer.

Installation

Hugo is cross-platform. There are multiple ways you can install it. These include using package managers, from source code, or with Docker. However, the easiest way to get it installed is using binaries. Hugo has pre-built binaries for macOS, Linux, Windows, FreeBSD, and OpenBSD. You can download them from Hugo's Github repository here. Be sure to install them on your path.

Once the installation is complete, run hugo --help on your terminal to ensure that the installation is complete and works. These are the first few lines you should see.

1$ hugo --help
2hugo is the main command, used to build your Hugo site.
3Hugo is a Fast and Flexible Static Site Generator built with love by spf13 and friends in Go.

Generating a Site

Select a location for the site source code to create a new site. Pick a site name and run the following command on your terminal in the location you picked.

1$ hugo new site <site-name>
2Congratulations! Your new Hugo site is created in <site-path>.

This command will generate a skeleton for your site. Most of the folders it generates are empty apart from archetypes. You may optionally add a theme and make slight config changes instead of building the site from scratch. You can find a range of themes at theme.hugo.io. Adding them is usually the same for most themes. Although, some may have slight variations. Change directories to the site folder, initialize a git repository, and add the theme as a submodule.

1$ cd <site-name>
2$ git init 
3$ git submodule add https://github.com/SteveLane/hugo-icon.git themes/hugo-icon 

To run the site locally, with the Hugo server, the theme, and some example configuration, run:

1$ hugo server -t hugo-icon --config themes/hugo-icon/exampleSite/config.toml

You can visit the site at localhost:1313 on your browser and you'll see this.

Site Structure

A typical Hugo site would have this structure:

1├── archetypes
2├── config
3├── content
4├── data
5├── layouts
6├── resources
7├── static
8└── themes

Archetypes

Archetypes serve as templates for content files. For example, the default archetype that is created when a site is generated looks like this:

1---
2title: "{{ replace .Name "-" " " | title }}"
3date: {{ .Date }}
4draft: true
5---

Any new content created using the hugo new command contains this as its front matter. Running hugo new posts/hello.md will create the following file in contents/posts:

1---
2title: "Hello"
3date: 2021-05-20T11:03:02
4draft: true
5---

You can create new archetypes with custom front matter and structure. When you create new content, an archetype for it is deduced from the path if not explicitly set using the --kind flag. For example, if a profile archetype exists at archetypes/profile.md, you can create a new profile in the content folder using hugo new profile/lisa-jane.md.

Assets

Assets are files that require processing before they can be served. Hugo pipes are the functions that perform asset processing. For example, let's say there exists a SASS file. Its path is assets/sass/form.sass. To convert the SASS to CSS, you will use the resources.ToCSS pipe.

1{{ $formSass := resources.Get "sass/form.sass" }}
2{{ $formStyling := $formSass | resources.ToCSS }}

Hugo pipes perform minification, bundling, JS processing among other functions.

Config

By default, Hugo site configuration is stored in the config.toml file at the site root. You can configure any number of things like cache, URL, site titles, live reload, content directories, archetype directories, languages, builds, the dev server, etc. You may choose to have multiple configuration files for better organization. In this case, these will be stored in the config folder. The config can also be specified using the --config flag with a Hugo command. Files used with this flag take precedence over other configs. Here is an example of the config file for the startup site created above:

1baseURL = "http://a-startup.com/"
2languageCode = "en-us"
3title = "My Startup Site"

Content

This is where the actual content of a site lives. In a blog, for example, the content will be all the posts, images, documents, and other resources. Hugo supports a variety of content types, including HTML and markdown. Typically content instances contain front matter which is the metadata of the instance. In posts/hello.md, the front matter is the title, date, and draft status. You create a container instance using the hugo new command.

Data

This folder contains your site's extra data to augment the content. They can be JSON, TOML, CSV, or YAML files. To get data from these files, you must reference the .Site.Data variable. Let's take the example of a coffee shop site with its menu in a data/menus/beverages.json file.

1{
2    "beverages": [
3        { "name": "Americano", "price": "$2.50" },
4        { "name": "Cappuccino", "price": "$3.75" },
5        { "name": "Espresso", "price": "$3.00" },
6        { "name": "Macchiato", "price": "$4.00" }
7    ]
8}

You can use this data in a template as follows:

1{{ range $.Site.Data.menus.beverages }}
2   {{ .name }}: {{ .price }}
3{{ end }}

Although the data folder is meant for static data files, it is still possible to fetch JSON and CSV data from external sources such as CMSs like Strapi or other APIs. You could use functions like getJSON and getCSV for these purposes. This allows for greater flexibility as you don’t have to build the site every time some data changes. With Strapi, you can add data to your backend and consume it on your Hugo site. You can find out more about how to access external data on your Hugo site here and how to get started on hosting your data with Strapi.

Layouts

These are the templates of the site. Hugo templates use the [text/template](https://golang.org/pkg/text/template/) and [html/template](https://golang.org/pkg/html/template/) packages in Go. They are written in HTML but variables and functions can be used inside nested curly braces {{ }} within them. Using logic and referencing external templates inside them is possible. You can find a great primer on this template language at this link.

Resources

The resource folder acts as a cache. The files generated as a result of asset processing as mentioned above are stored here.

Static

Images, CSS, Javascript, and other static content are placed in this folder.

Themes

Themes added to a site are put in this folder. In the example site we generated above, we placed its theme here.

Functions

Within templates, you can use built-in Go and Hugo functions and tools. For example, in the archetypes/default.md, you may have noticed this:

1title: "{{ replace .Name "-" " " | title }}"

replace is a function that replaces part of a string with something else. In this case, the file name is the input, and all the - characters are removed then replaced with a single space. title is also a function that converts a string to a title case. These are just a few examples. More are listed in Hugo's function reference.

Variables

Hugo makes inbuilt and config-defined values accessible to templates. These include variables that hold information about the site, pages, taxonomies, content, menus, and other files. For example, the global [.Site](https://gohugo.io/variables/site/#site-variables-list) variable holds site-related values like languages, sections, the site title, the base URL, etc.

Pipes

As mentioned earlier, Hugo pipes are functions that transform site assets. Some common uses of pipes include converting SCSS/SASS into CSS, resource minification, resource bundling, fingerprinting, and a host of other functions.

Advanced Features in Hugo

Once you're comfortable with the basics, it's time to explore Hugo's advanced features. These tools will take your site to the next level.

Custom Taxonomies

Organize your content with custom taxonomies. Whether you're categorizing blog posts or tagging products, Hugo makes it simple. Add custom taxonomies in your config.toml:

1  category = "categories"
2  tag = "tags"

Shortcodes

Shortcodes let you add dynamic content to your Markdown files. For instance, you can create a custom shortcode to embed YouTube videos. Add a new shortcode in the layouts/shortcodes directory and use it in your content:

{{< youtube "dQw4w9WgXcQ" >}}

Multilingual Support

Reach a global audience with Hugo's multilingual support. Configure languages in your config.toml:

1  [languages.en]
2    weight = 1
3    languageName = "English"
4  [languages.fr]
5    weight = 2
6    languageName = "Français"

Custom Output Formats

Need to generate different file types? Hugo's got you covered. Define custom output formats in your config.toml:

1  [outputFormats.CustomXML]
2    mediaType = "application/xml"
3    baseName = "custom"

Image Processing

Optimize and manipulate images with Hugo's built-in tools. Use the resources functions to resize, crop, and process images directly in your templates.

Optimizing a Hugo Site for SEO

SEO is crucial for driving traffic to your site. Hugo offers several features to help you optimize for search engines.

Setting Titles and Meta Descriptions

Use front matter to set titles and meta descriptions for each page. These elements are key for SEO. Here's an example:

1title: "My First Post"
2description: "An in-depth look at my first post."

Managing Sitemaps

Hugo can auto-generate sitemaps to help search engines crawl your site. Enable sitemaps in your config.toml:

1  changefreq = "weekly"
2  priority = 0.5

Using Canonical URLs

Avoid duplicate content issues by setting canonical URLs. Add the canonical URL in your front matter:

1canonicalURL: "http://example.org/my-first-post/"

Mobile-Friendly Design

Ensure your site is mobile-friendly. Use responsive design principles and add the viewport meta tag in your templates:

Social Media Integration

Enhance your site's visibility on social media by adding Open Graph and Twitter Card metadata. Include these tags in your templates:

Types of Sites You Can Build with Hugo

So, what can you actually do with Hugo? A lot. Here are some examples to get your creative juices flowing.

Blogs and Personal Sites

Hugo is perfect for fast-loading blogs and personal sites. With its powerful templating system, you can create a unique look and feel without sacrificing performance. Plus, managing content is a breeze with Markdown files.

Corporate Websites

Need a sleek, professional site for your business? Hugo's got you covered. Its speed and scalability make it ideal for large-scale corporate websites. You can easily integrate with other tools and services to create a seamless experience for your users.

E-commerce Sites

Believe it or not, you can even build e-commerce sites with Hugo. While it might not have the built-in features of platforms like Shopify, you can use Hugo to create beautiful product pages and catalogs. Combine it with a headless CMS like Strapi for a powerful, flexible e-commerce solution.

Knowledge Bases

Building a knowledge base? Hugo's speed and flexibility make it an excellent choice. You can organize your content with custom taxonomies and create a user-friendly experience with Hugo's templating system.

Portfolios

Showcasing your work has never been easier. Hugo's themes and templates allow you to create stunning portfolios that load in the blink of an eye. Whether you're a photographer, designer, or developer, Hugo helps you put your best foot forward.

Benefits of Using Hugo

You're probably wondering, "Why should I choose Hugo over other tools?" Let's break it down.

Speed and Performance

Hugo can generate thousands of pages in seconds, ensuring your site loads quickly and efficiently. This speed is crucial for user experience and SEO, making Hugo a top choice for performance-conscious developers.

Ease of Use

Despite its power, Hugo is incredibly easy to use. The setup is straightforward, and the documentation is extensive. You don't need to be a command-line wizard to get started, but if you are, you'll appreciate the advanced features Hugo offers.

Flexibility

Hugo offers unparalleled flexibility. Its templating system allows for extensive customization, so you can create a site that looks and functions exactly how you want. Plus, with support for custom taxonomies, shortcodes, and more, the possibilities are endless.

Scalability

Hugo can handle large volumes of content without breaking a sweat. Whether you're managing a small blog or a massive corporate site, Hugo scales effortlessly. This scalability ensures that your site remains fast and efficient, no matter how much content you add.

Strong Community Support

Hugo's community is vibrant and active. You'll find extensive documentation, forums, and tutorials to help you along the way. Whether you're a beginner or an experienced developer, the community is there to support you.

Tips for Customizing Hugo Themes

Customization is where Hugo truly shines. Here are some tips to make your site stand out.

Modifying Theme Files

Edit the HTML and CSS files in your theme to match your brand. For instance, change the color scheme or typography to reflect your style.

Creating Custom Templates

Build unique page layouts by creating custom templates. Add new templates in the layouts directory and reference them in your front matter:

layout: "custom-layout"

Using Partials for Reusability

Simplify your templates by using partials. Create reusable components in the layouts/partials directory and include them in your templates:

{{ partial "header.html" . }}

Enhancing Themes with JavaScript

Add interactivity to your site with JavaScript. Include your scripts in the static/js directory and link to them in your templates:

Managing CSS and JS Assets

Optimize and organize your static assets. Use tools like Hugo Pipes to minify and bundle your CSS and JavaScript files.

Using Data Files

Feed dynamic data into your templates with data files. Store JSON, YAML, or TOML files in the data directory and access them in your templates:

1  <p>{{ .name }}</p>
2{{ end }}

Is Hugo Worth It in 2024?

With so many static site generators out there, you might be wondering if Hugo is still worth it. Spoiler alert: it is.

Hugo vs. Modern Static Site Generators

Hugo continues to hold its own against newer competitors. Its speed, simplicity, and flexibility make it a top choice for developers. While tools like Next.js and Nuxt.js offer modern frameworks, Hugo's ease of use and performance remain unmatched.

Real-World Use Cases

Hugo powers a wide range of sites, from personal blogs to large corporate websites. Companies like Strapi use Hugo to deliver fast, reliable content to their users. Its versatility makes it suitable for any project.

Community and Support in 2024

Hugo's community is as strong as ever. You'll find extensive documentation, active forums, and countless tutorials to help you along the way. Whether you're a newbie or a seasoned pro, the community has your back.

How to Deploy a Hugo Site

Here are some popular options to get your Hugo site live.

Deploying to Netlify

Netlify is a popular choice for hosting Hugo sites. Sign up for a free account, connect your Git repository, and let Netlify handle the rest. It even offers continuous deployment, so your site updates automatically with each commit.

Using GitHub Pages

GitHub Pages is another great option. Push your Hugo site to a GitHub repository, then configure GitHub Pages to serve your site. Use GitHub Actions for automated builds and deployments.

Hosting on Vercel

Vercel makes deployment a breeze. Sign up, connect your repository, and deploy your site with a single click. Vercel also offers serverless functions and edge caching for optimal performance.

Deploying to AWS S3

For more control, consider hosting on AWS S3. Upload your static files to an S3 bucket, configure it for static site hosting, and use AWS CloudFront for global content delivery.

Automating Deployments

Set up CI/CD pipelines for automated deployments. Tools like Jenkins, Travis CI, and GitHub Actions can streamline your deployment process, ensuring your site is always up-to-date.

Future of Hugo

Hugo continues to evolve with regular updates and new features. The developers are committed to maintaining its speed and simplicity while adding powerful new capabilities. Expect Hugo to remain a top choice for static site generation in the years to come.

Conclusion

Hugo is an excellent static site generator that is fast and feature-rich. You can do so much with it and it offers great flexibility when working with site content. What we've covered here is just the tip of the iceberg. You can read about more exciting ways to use it in the Hugo documentation.

This article is a guest post by Zara Cooper. She wrote this blog post through the Write for the Community program.