Hugo Content Guide

In this guide

Introduction

Hugo is a static site generator — it takes a set of content files and layout templates, and uses them together to build a complete website. Hugo makes writing content simple because it allows you to work in files which contain only the main content of the page.

Directory structure

The main directories in our Hugo project are structured like this:

├── archetypes
├── assets
├── config
├── content
├── data
├── i18n
├── layouts
├── public
├── resources
├── static

archetypes: Contains archetype templates which can be used as starting points for creating new content.
assets: Contains source files for JavaScript and CSS assets.
config: Contains the Hugo configuration files.
content: Contains the HTML content files.
data: Contains raw data files which are used by Hugo.
i18n: Contains translations of text snippets which are used in templates.
layouts: Contains templates which are used to build the site’s HTML files.
public: Stores the site built by Hugo. Don’t modify anything in this directory.
resources: Used by Hugo to store processed assets and images. Don’t modify anything in this directory.
static: Contains all of the site’s files which aren’t HTML content. This is where you place things like image files and PDFs.

Writing content

All content files are stored in the content directory and are given a .html file extension. They are written using HTML markup and include only the main content of the page. When writing content for the site, you don’t need to add things like meta tags, the site header, the navigation links, the footer, etc. — Hugo will take care of adding those for you when it builds the site.

Front matter

Front matter is a special block of code in your content files which contains metadata for the page. It’s placed at the very top of the file, above the HTML. Here’s an example of what it looks like:

---
title: Accounts & services
description: "Self-service options: submit meter readings, moving information, payment options, and update your account information."
menu: main
---

The front matter block is not part of the content of the page, Hugo uses the variables you specify within it to generate things like the title tag and meta tags for the HTML page.

Front matter variables

Here are some of the variables that you’ll most commonly be using:

title: The title of the page. This is used in the <title> tag, in metatags and in breadcrumbs.
description: A short description of the page contents. This is used in meta tags and will show up in search engine results.
linktitle: Optional. Used as the text for breadcrumb links, instead of the title. Use this when the regular title is too long.
menu: Optional. The name of the menu that the page belongs to. Use either main or footer.
parent: Optional. The path to the page’s direct parent page. This is used to generate breadcrumbs. You don’t need to include leading or trailing slashes, for example: parent: accounts_and_services/frauds_and_scams.
images: Optional. A list of URLs for images which are related to the page. The images will be shown when the page is shared on social media.
banner: Optional. The name of the banner image to be placed at the top of the page, above the content.
draft: Optional. You can add draft: true to the front matter of any page to prevent it from being published to the live site.
publishDate: Optional. Set this to the date on which the page should be published. Use the format YYYY-MM-DD. If set to a future date, the page will not be published to the live site before that date.

See full list of available front matter variables.

Metadata

In addition to the Front Matter data, every content file should include metadata about its content strategy and its content owners. The metadata information can be included as comments at the top of the Front Matter block, like in the following example.

---
##
# Page title
#
# Content strategy
# ------------------------------------------------------------------------------
# Audience (Who is visiting this page?):
# The people who care.
#
# Goals (What is the audience’s intent or goals?):
# To get sh!t done.
#
# Actions (What primary action does the audience need to accomplish?):
# - Keep fit.
# - Have fun.
#
# Narrative (What is the story to support the user’s journey?):
# I’m all alone. I’m rolling a big doughnut and this snake wearing a vest…
#
# Success metrics (What are we measuring on this page?):
# How many licks it takes to get to the centre.
#
# Content owners
# ------------------------------------------------------------------------------
# - Dan Betcher (Marketing)
# - Dan Boulet (Marketing)
##
title: Page title
description: "Page description example."
menu: main
keywords:
    - page
    - example
layout: landing-page
---

The content strategy section needs to contain these five data points: audience, goals, actions, narrative, and success metrics. The content owners section should contain a simple list which includes each owner’s name and department.

Index files

All index files within the content directory must be named _index.en.html or _index.fr.html. Make sure to include the leading underscore in the file name, as this is required by Hugo.

Navigation menus on the site are generated based on the menu front matter variables that are defined for pages. The main menu is used to populate the navigation in the header, the sidebar, the breadcrumbs and tertiary links.

Content translation

All files within the content directory must include a language suffix in their file name. The suffix must be either .en or .fr, and be inserted just before the .html part of the file name. For example:

site_map.en.html
site_map.fr.html

Files which share the same path and base filename (the part of the file name which comes before the language suffix), will be linked together as translated pages.

Forms

When a page includes a contact form, it should use front matter which resembles the following example:

---
title: Accessibility requests and feedback
description: ""
parent: accessibility
layout: form
---

It’s important to include the following variables in the front matter:

layout: Set this to layout: form.

Form action attribute

The opening <form> tag on your page should resemble this:

<form class="full-form" action="{{< include partial="content/form-handler-url" >}}" method="post">

The action attribute on the tag should be set to {{< include partial="content/form-handler-url" >}}. This is a special shortcode which will allow Hugo to automatically insert the correct form handler URL.

Form settings

The HTML content of the form should include the form-settings shortcode, inserted immediately before the closing </form> tag:

    {{< form-settings
        mail_to="phNLj5Nld4bv5Y4nd6hLP2YbNE3mV96pf4XIs3wa/q4="
        mail_from="CPbnAbVjXfebFejB3kwhZ2bodxrIlyCoKacihxLPSx8="
        response_page="/accessibility/feedback_thank_you/"
        department="AREQ"
        field_names="header1:header=4; header2:header=4; header3:header=4; contact_name:required=text; street_address:required=text; city:required=text; postal_code:required=text;"
        mail_subject="Accessibility request or feedback"
    >}}
</form>

Change the parameter values to suit your form. This replaces the various hidden input tags that we have used in the past.

Form thank you pages

Form thank you pages are a special type of page that users see after they successfully submit a form. A form thank you page should include front matter like this example:

---
title: Accessibility requests and feedback - Thank you
linktitle: Accessibility requests and feedback
description: ""
parent: accessibility
layout: form-thank-you
private: true
---

It’s important to include the following variables in the front matter:

linktitle: For this value, use the associated form page’s title.
layout: Set this to layout: form-thank-you.
private: Set this to private: true. This will prevent the page from appearing in search results and site maps.

Landing pages

Landing pages use special layout templates which don’t include a sidebar. Examples of landing pages on our current site are the index pages for the MyBill, Safety, and Your home sections. To create a landing page, add layout: landing-page to the page’s front matter.

Article pages

Article pages are a special type of content which are used in the corporate blog. As opposed to other types of content which are written in HTML, articles are written in Markdown and their file name ends in either .en.md or .fr.md.

All article pages are placed in the content/articles/ directory. The pages in this directory are organized by year and month, in a structure which looks like this:

└── content
    └── articles
        ├── …
        ├── 2020
        |   ├── 01
        |   ├── 02
        |   ├── …
        |   └── 12
        ├── 2021
        |   ├── 01
        |   ├── 02
        |   ├── …
        |   └── 12
        └── 2022
        |   ├── 01
        |   ├── 02
        |   ├── …
        |   └── 12
        ├── …

When creating a new article, place the Markdown file in the directory which corresponds to the article’s publish date. Use the title of the article as the file name, using only lowercase letters and replacing spaces and special characters with underscores.

For example, an article published in September 2020 with the title “Manitoba Hydro releases 2019–20 Annual Report” would be placed in content/articles/2020/09/ and be named manitoba_hydro_releases_2019_20_annual_report.en.md.

The front matter for article pages looks like this:

---
title: Temporary generators installed at Pukatawagan
subtitle: Power supply allows residents to return home while repairs to transmission line underway
publishDate: 2022-08-17
description: "Manitoba Hydro energized two large industrial generators to bring power back to the community of Pukatawagan."
summary: "In Pukatawagan, Manitoba Hydro energized two large industrial generators to bring power back to the community of while we work to replace 77 fire-damaged poles on the power line."
categories:
- News releases
featured:
- home
images:
- /assets/img/featured_thumbnails/temporary-generators-installed-pukatawagan-1.jpg
coverImage:
    src: /assets/img/figurebox/temporary-generators-installed-pukatawagan-1.jpg
    alt: A crane moving a large metal fuel tank off a train car and onto the ground nearby.
    caption: Fuel tanks for temporary generators being installed near rail lines.
---

In addition to the title and description variables, it’s important to include the following variables in the front matter:

publishDate: This is the date that the article is published to the site. Use the format YYYY-MM-DD.
summary: Include a short introductory text here to be used in article teasers. Try to limit its length to 60 words or less. If omitted, Hugo will generate a summary from the article’s content.
categories: Format this as a list. Every article should have at least one category. Choose from the following list: History, How our system works, In your community, Keeping you safe, News releases, Our environment, Working for you.

You can also include these optional variables:

coverImage: An image to be displayed in the article header. Format it as an image object which includes src and alt.
featured: A list of names of featured areas where the article should be displayed. The only option for now is home.
related: A list of permalinks to related articles, or set to none to remove related articles from the page.
subtitle: The subtitle to display under the article’s main heading.
tags: A list of tags to apply to the content. These are not displayed to users, but are used to organize content.

Article content guidelines

To make reading more comfortable for users, long runs of text within articles should be formatted into digestible chunks. Break them up with the help of headings, figureboxes, section dividers and pull quotes, where appropriate.
The layout with the large cover image is reserved for long-form articles (over 1000 words). Shorter articles should use the normal size.
Articles within the news releases category should be kept basic and should not include cover images or related articles.

Please note: the template used for article pages will automatically insert an <h1> tag above the content, so you should not include an <h1> in your page content.

Error pages

These are displayed as custom error pages when something goes wrong with the site. For example, the 404.html page is used when users see a “Page not found” error. These files should be placed in the content/error directory and must include an errorCode front matter variable.

Shortcodes

Shortcodes are small code snippets that help you to include reusable components in your content. You can embed shortcodes anywhere inside your content.

To use a shortcode in your content, write it like this: {{< shortcode-name >}}, replacing shortcode-name with the name of the shortcode that you want to use. For example, here’s a shortcode which is used to embed a search form, called search-block:

{{< search-block >}}

For certain shortcodes, you can also add extra parameters after the shortcode name. They are written much in the same way as HTML tag attributes, and look like parameter="value". For example, you can add a title to a search form by writing a shortcode like this:

{{< search-block title="Looking for something specific?" >}}

The great thing about shortcodes is that they allow you to embed complex components in your content, without having to deal with large chunks of HTML.

List of shortcodes

The list of available shortcodes is currently limited, but will be expanded in the future to make it easier to embed things like videos and images inside of your content. Here are a few shortcodes which are currently available.

`form-handler-url`

Used to insert the form handler URL in forms.

`form-settings`

Used to embed special hidden inputs within forms.

`hero-banner`

Used to embed a full-width banner on landing pages.

`search-block`

Used to embed a search form.

See the full list of available shortcodes.

Previewing content

In order to preview your site content changes, you need to tell Hugo to rebuild the site files. Our Hugo project includes scripts to help you with this, the two commands you will need are:

build: Rebuilds the entire site from scratch.
watch: Runs in the background, watching for content changes and rebuilds the site as needed. While this is running, you can open http://local.hydro.mb.ca:1313/ in your browser to see an auto-refreshing preview of the site.

If you use Visual Studio Code, you can run these commands directly in the app using the npm scripts panel, located in the bottom left corner of the app. Otherwise, these scripts can be run from the Terminal, using the commands yarn build and yarn watch.