Hugo Cheatsheet

I found it fitting to create a quick cheatsheet on Hugo, since that is the tool I used to build this website. The main purpose of this cheatsheet will be for my own personal benefit to revisit some of the common hugo commands I use during development of this site. Hopefully, someone else may also find this cheatsheet useful.

This is not an exhaustive list of all of hugo’s functionality, but instead, it is a hyper-personalized view into how I personally use hugo, which commands I use, and my understanding of how the tool works.

Archetypes

I like to think of archetypes as templates. Unfortunately, the concept of a “template” is already taken by the templating engine in Hugo that is responsible for “filling in” html documents with content.

While templates are html documents for content, archetypes are templates for types of content. More concretely, the archetype controls the default front-matter that appears for different content types.

The content of my post.md file in my archetypes directory looks like this as of this moment:

---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
description: "Example article description"
thumbnail: ""
lead: "Example lead - highlighted near the title"
disable_comments: true
authorbox: true
toc: true
mathjax: false
categories:
- "Category 1"
- "Category 2"
tags:
- "Test Tag"
- "Test Tag2"
---

When I execute hugo new cheatsheet/<name of cheatsheet here>.md, then hugo will pull in the above yaml front-matter and place it into the new cheatsheet markdown file automatically. This is a great starting point so I don’t have to remember the names of specific front-matter variables.

Sections

A concept closely related to archetype are sections. The slug (url not including the root domain) to this specific page on this site is /cheatsheet/hugo_cheatsheet/. In this case, cheatsheet is the section. Hugo does this because this specific page is located in <hugo root>/content/cheatsheet/Hugo Cheatsheet.md.

Hugo assumes that the way you separate your content during development is the way you want your content separated on your site.

Also, when you use the new command, hugo looks for a match between:

• anything before the “/” in your new command
• section name in your content directory
• an archetype file in your archetype directory

Themes

Hugo provides a fairly extensive list of themes available. The main theme I’m using is Mainroad because it is simple and has all of the features/functionality that I expect.

There are also extensive instructions on both Hugo’s site as well as the theme’s github for installing and configuring themes.

Getting Started Commands

You likely won’t be building new sites very often, but here is the command for reference.

# build directory structure of new site
hugo new site <name of site>

Common commands

Create new content

When creating new content, you can also specify the section. Keep in mind, this section will likely correspond to an archetype if you also created one (for default front-matter):

hugo new <section name>/<page name>.md

# example for creating this page:
hugo new cheatsheet/hugo_cheatsheet.md

In the above example, I am using the cheatsheet section/archetype. To my knowledge, the archetype that corresponds to a section must have the same name as that section.

Build and serve the site

# builds the site from raw .md file content
hugo

# builds the site, but also includes "draft" content
hugo -D

Deployment

There are a few types of deployments I’m interested in learning more about.

• Run your own web server like nginx, apache, etc. on a cloud host provider
  • be careful with security and config settings here…
• Netlify
• AWS S3 static site
• Azure blob static site
  • this option is in “preview” as of me initially writing this doc

Although it would be interesting to run my own web server, I think I would end up spending all of my time tinkering and never actually publish content. My goal here is to shrink the gap between my thoughts and the final published content of my site.

I will be targeting the Azure blob static site for my deployment.