Working with Hugo

Hugo front matter

Chainguard Academy runs as a static Hugo site. As such, each page of content on the site must begin with what's called Hugo front matter. Front matter allows you to add special metadata about a given page.

A typical front matter section looks like this:

---
title: "How to Use Chainguard Images"
linktitle: "How to Use"
type: "article"
description: "A primer on how to migrate to Chainguard Images"
lead: "A primer on how to migrate to Chainguard Images"
date: 2022-09-01T08:49:31+00:00
lastmod: 2024-03-29T19:42:31+00:00
draft: false
tags: ["Chainguard Images", "Procedural", "Product"]
images: []
menu:
  docs:
	parent: "chainguard-images"
weight: 020
terminalImage: academy/chainguard-images:latest
toc: true
---

The following should be in every page's front matter:

• title: The title of the given doc. The value should be in quotes and written in Title case.
• linktitle: The "short title" of a given doc that appears in the left-hand navigation menu. If no linktitle is given, Hugo will default to using the full title in places where the linktitle would appear.
• type: We only have one "content type" defined for Chainguard Academy. This field should always be set to article.
• description: A brief, one- or two-sentence description of the resource.
• date: A timestamp showing the date of initial publication.
• lastmod: A timestamp of the most recent edit to the page.

Note: You should only update the lastmod field of a resource's front matter when it has been fully reviewed and tech tested. Otherwise, it can mess with our automated maintenance reporting.

• draft: If sent to true, the resource will be hidden from view when published to Academy. This should generally be set to false.
• tags: The tags with which to associate the given resource. In general, there should be at least three tags on each resource. Also, tags should always be written in all caps.
• menu: If set, Hugo adds the page to the given menu or menus.
• weight: This is the "weight" of content pages in the lefthand nav, higher weights appear lower in lists.
• toc: This should almost always be set to true - this will allow a table of contents to appear at the right side of the resource.

Organizing resources in Hugo

Chainguard Academy resources are organized based on their location within the Hugo filesystem in the content/ directory. Each piece of content should reside in what we refer to as "buckets"

You can organize resources within the same bucket by assigning them a weight value in the Hugo front matter. Docs with higher weights will appear lower in, say, the left-hand navigation menu.

It often makes sense to organize docs in Alphabetical order (as in the case of our Vulnerability Comparison docs) but other times we may want to sort docs for different purposes. For example, docs in the Working with Images bucket are sorted by what we think readers will want to know first.