Editing a Page #

If you followed the instructions in the Getting Started section to checkout the repository and serve the handbook locally you can edit a page locally. However, as you may have noticed, at the bottom of each page is a link to edit the page in the GitHub web editor if you would prefer. This may be easy for making small changes.

Pages #

Each page is a Markdown file with YAML front matter followed by the page contents in Markdown.

Front Matter #

The front matter is used to define various pieces of metadata related to a page. The front matter appears at the top of a content file. In the handbook we format front matter as YAML, preceded and followed by three hyphens.

---
title: "Example Page"
weight: 1
---

The full YAML specification is long and comprehensive. The most important thing to understand here is that the front matter YAML consists of keys and values separated by a hyphen. For example, in the expression weight: 1, weight is the key with a value of 1.

If you created a page using hugo new then some boilerplate front matter with explanatory comments should already be present. If you are editing an existing page there should already be front matter.

Most of the time, the only keys you will need to consider are title and weight.

title

The title of a page as it appears in the navigation menu

weight

Determines the order of pages in the navigation menu. Smaller numbers appear first

The Hugo documentation details a set of predefined front matter keys. Other valid fields related to the handbook theme are documented in the theme’s README.

Content #

After the front matter is the content section.

---
title: "Example Page"
weight: 1
---

| content section |

The content section is formatted in Markdown. The following links from Markdown Guide describe basic and extended Markdown syntax.

Not all of the extended Markdown syntax may be implemented by Hugo’s Markdown renderer.

Shortcodes #

Shortcodes are templates (which can be parametrised) and included the content section. They can be particularly useful for including more complex features than Markdown’s simple syntax will allow. Using a shortcode is preferable to including raw HTML in a content file.

Shortcodes can called in Markdown content files the following way

{{% shortcode parameter %}}

Some shortcodes may have an opening and closing tag, similar to HTML

{{% shortcode %}} content to process {{% /shortcode %}}

Hugo Shortcodes #

Hugo has a set of useful built-in shortcodes.

In particular

• figure
• gist
• highlight
• param
• ref and relref

Theme Shortcodes #

The theme has a number of shortcodes which may be helpful.

In particular

• hints
• expand
• KaTeX
• tabs

Repository Shortcodes #

Shortcodes can be included in the handbooks repository. For more information see Creating Shortcodes

repo_link #

Create a link to a file or directory in the handbook’s repository.

{{% repo_link path="README.md" text="README" %}}

path

Path to the file or directory relative to the root of the repository

text

Text of the link (can include Markdown formatting)