Graph View

Hugo

🔗 Related cheat sheets:

  • 🧾 Markdown: hugo_markdown.md
  • 🎨 Themes and addons: hugo_themes-and-addons.md

Goal: fastest path from zero to a solid Hugo site.

⚡ One-shot quickstart

Assumes Hugo is installed.

# 1) Create a new site and enter it
hugo new site my-site
cd my-site
 
# 2) Create your first post from the default archetype
hugo new posts/my-first-post.md
 
# 3) Run the dev server (serves drafts)
hugo server -D

⚙️ Install and basics

🏗️ Create a new site

  • Create skeleton in a new folder:
    • hugo new site my-site
  • Change into it and run the dev server:
    • cd my-site
    • hugo server -D
  • Dev server basics:
    • Watches files and rebuilds on change.
    • Draft content (draft: true) only shown with -D.
    • Stop with Ctrl + C.

📁 Core project structure

Default tree (without a theme):

my-site/
  archetypes/   # content blueprints (front matter defaults)
  assets/       # pipeline-able assets (SCSS, JS, etc.)
  content/      # Markdown and other content
  data/         # JSON/YAML/TOML data files
  i18n/         # translation strings
  layouts/      # templates, partials, baseof
  static/       # passthrough files (images, fonts...)
  themes/       # optional themes
  hugo.toml     # site configuration

Key ideas:

  • content/ drives sections and URLs.
  • layouts/ is matched by type, section, and kind (single, list, home, taxonomy, term).
  • static/ is copied as-is to the site root.
  • assets/ is only used via Hugo Pipes (resources.* in templates).

🧱 Blog layout pattern example

Minimal blog structure and matching templates:

content/
  _index.md        # home page (optional)
  posts/
    _index.md      # posts list
    my-first-post.md
 
layouts/
  _default/
    baseof.html
    single.html
    list.html
  posts/
    single.html    # optional override for posts only
  • Home can use layouts/index.html or layouts/_default/list.html.
  • content/posts/_index.md uses the list template to render a posts overview.
  • Individual posts use layouts/_default/single.html or layouts/posts/single.html if present.

📝 Content basics

  • Create content with an archetype:
    • hugo new posts/my-first-post.md
  • Sections:
    • Each first-level folder under content/ is a section (posts, docs, blog…).
  • Common front matter fields:
    • title, date, draft, tags, categories, slug, summary, description, weight.
  • Kinds (how Hugo sees a page):
    • single: an individual page.
    • list: a section listing (content/posts/_index.md).
    • home: the site root.
    • taxonomy and term: lists for tags/categories.

🧾 Archetypes

  • Archetypes provide default front matter per section.
  • Global default:
    • archetypes/default.md
  • Section-specific:
    • archetypes/posts.md for content/posts/*
  • When you run hugo new, Hugo merges the archetype with any CLI parameters.

Example archetypes/posts.md:

+++
title = "{{ replace .Name "-" " " | title }}"
date = {{ .Date }}
draft = true
+++

🧩 Templates in 60 seconds

  • Base template:
    • layouts/_default/baseof.html

Example baseof.html:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ block "title" . }}{{ .Title }} | {{ .Site.Title }}{{ end }}</title>
  </head>
  <body>
    {{ block "main" . }}{{ end }}
  </body>
</html>
  • Content templates:
    • layouts/_default/single.html for single pages.
    • layouts/_default/list.html for section and taxonomy lists.

Example single.html:

{{ define "main" }}
  <main>
    <h1>{{ .Title }}</h1>
    {{ .Content }}
  </main>
{{ end }}
  • Partials:
    • layouts/partials/header.html
    • Called with {{ partial “header.html” . }}

🌐 Taxonomies and menus

  • Enable taxonomies in hugo.toml:
[taxonomies]
  tag = "tags"
  category = "categories"

  • Use front matter fields tags and categories to populate lists.

  • Basic menu in config:

[menus]
  [[menus.main]]
    name = "Home"
    pageRef = "/"
    weight = 1
 
  [[menus.main]]
    name = "Blog"
    pageRef = "/posts"
    weight = 2

⚙️ Configuration essentials (hugo.toml)

Minimal example:

baseURL = "https://example.com/"
title = "My Hugo Site"
# theme = "my-theme"  # or prefer Hugo Modules (see themes and addons cheat sheet)
defaultContentLanguage = "en"
 
[params]
  author = "You"
  description = "Quick Hugo site"
  • Markup and highlight settings live under the [markup] table (see Hugo Markdown cheat sheet).
  • baseURL must be the final public URL for correct absolute links.

🧪 Useful CLI flags

  • hugo server -D -E -F
    • Include draft, expired, and future content.
  • hugo server —disableFastRender
    • Safer but slightly slower rebuilds when template logic is complex.
  • hugo server —renderToDisk
    • Write rendered files to public/ while running the dev server.
  • hugo —minify
    • Minify HTML, CSS, JS at build time.

⚠️ Gotchas

  • Draft content with draft = true is not rendered unless you run hugo server -D or set draft = false.
  • A wrong baseURL in hugo.toml leads to broken absolute links and assets in production; always set it to the public site URL.
  • Site layouts/ override theme layouts/ due to Hugo’s union file system; if a template change seems ignored, check for an override.
  • Using different Hugo versions locally and in CI can cause subtle build differences; keep them aligned.

🚢 Build and deploy

  • Production build:
    • hugo —minify
  • Output ends up in public/ by default.
  • Typical deployment paths:
    • Push public/ to any static host (Netlify, Vercel, S3, GitHub Pages, custom nginx).
    • Or configure your host to run hugo during CI/CD.
  • Keep hugo version in sync across local and CI for reproducible builds.
  • Official deployment docs: https://gohugo.io/hosting-and-deployment/
Properties3
descriptionA quickstart and structure cheat sheet for the Hugo static site generator.
tagshugo, ssg, web-dev
aliaseshugo-cheat-sheet, hugo-core

Backlinks