Hugo is a great static site generator. The build times are pretty fast and there are theme which we can use. A lot of Hugo apis are available to setup a static site which is like a blog / personal website / documentation.

Here are some cool themes

Setting up hugo

  1. Initialize a new hugo site
hugo new site mysite --format=yaml
  1. Add a theme ( using papermod as an example )
cd mysite
git init
git submodule add --depth=1 https://github.com/adityatelange/hugo-PaperMod.git themes/PaperMod
  1. Add the theme to the config file
theme: "PaperMod"
  1. Adding content

Any markdown files added in the folder content will be rendered as a page. Hugo follows route based on folder structure.

For folders, the folder name is the route and it will render a list page.

hugo new posts/my-first-post.md

Contents can have front matter which is used to set the metadata for the page. These values can also be used in the html templates to render the page.

example:

---
title: "My First Post"
date: 2024-02-03T12:07:02+07:00
draft: true
slug: "my-first-post" # This is the url for the page
---
  1. Running the server
hugo server -D

Overriding theme

The theme can be overriden by adding a file with the same name in the layouts folder. This is useful to customize the theme to our needs.

Hugo scans for the files in the following order

  1. The layouts directory in the root of your project
  2. The layouts directory in the theme

There are special files in hugo

  • layouts/index.html - The home page
  • _default folder will have the default layout for the site
    • baseof.html - The base layout for all the pages
    • single.html - The layout for a single page
    • list.html - The layout for a list of pages
  • partials folder will have the partials for the site
  • shortcodes folder will have the shortcodes for the site

Shortcodes

Shortcodes are html blocks which will be replaced in the markdown files.

which is used like this

{{ < shortcode > }}

Hugo has some built in shortcodes

  • figure - To add images with captions
  • gist - To add github gists
  • highlight - To add code blocks
  • instagram - To add instagram posts
  • tweet - To add tweets
  • vimeo - To add vimeo videos
  • youtube - To add youtube videos
  • ref - To add references to other pages
  • param - To add frontmatter parameters to the shortcode

We can also add custom shortcodes. by adding html in the shortcodes folder.

For example, to add a youtube video to the markdown file, we can use the following shortcode

shortcodes/youtube.html

<iframe width="560" height="315" src="https://www.youtube.com/embed/{{ index .Params 0 }}" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

and it can be used in the markdown file as

{{ < youtube 123456 > }}

The above code will be replaced by the html code to embed the youtube video.

Conclusion

This is a basic overview of getting started with hugo. There are a lot of features in hugo which covers a lot of usecases for buildling a website. The documentation is pretty good and there are a lot of themes available to get started with.

Some terms to get started with hugo