Contribute to the Hugo Docs

Documentation is a critical component of any open-source project. The Hugo docs were completely reworked for the release of v0.20, but there is always room for improvement.

Create Your Fork

It’s best to make changes to the Hugo docs on your local machine to check for consistent visual styling. Make sure you’ve created a fork of Hugo on GitHub and cloned the repository locally on your machine. For more information, you can see GitHub’s documentation on “forking” or follow along with Hugo’s development contribution guide.

You can then create a separate branch for your additions. Be sure to choose a descriptive branch name that best fits the type of content. The following is an example of a branch name you might use for adding a new website to the showcase:

git checkout -b jon-doe-showcase-addition

Adding New Content

The Hugo docs make heavy use of Hugo’s archetypes feature. All content sections in Hugo documentation have an assigned archetype.

Adding new content to the Hugo docs follows the same pattern, regardless of the content section:

hugo new <DOCS-SECTION>/<new-content-lowercase>.md

Adding a New Function

Once you have cloned the Hugo repository, you can create a new function via the following command. Keep the file name lowercase.

hugo new functions/newfunction.md

The archetype for functions according to the Hugo theme is as follows:

archetypes/functions.md
---
linktitle: ""
description: ""
godocref: ""
publishdate: ""
lastmod: ""
categories: [functions]
tags: []
ns: ""
signature: []
workson: []
hugoversion: ""
aliases: []
relatedfuncs: []
toc: false
deprecated: false
needsexamples: true
---

New Function Required Fields

Here is a review of the front matter fields automatically generated for you using hugo new functions/*:

title
this will be auto-populated in all lowercase when you use hugo new generator.
linktitle
the function’s actual casing (e.g., replaceRE rather than replacere).
description
a brief description used to populate the Functions Quick Reference.
categories
currently auto-populated with ‘functions` for future-proofing and portability reasons only; ignore this field.
tags
only if you think it will help end users find other related functions
signature
this is a signature/syntax definition for calling the function (e.g., apply SEQUENCE FUNCTION [PARAM...]).
workson
acceptable values include lists,taxonomies, terms, groups, and files.
hugoversion
the version of Hugo that will ship with this new function.
relatedfuncs
other [templating functions][] you feel are related to your new function to help fellow Hugo users.
{{.Content}}
an extended description of the new function; examples are not only welcomed but encouraged.

In the body of your function, expand the short description used in the front matter. Include as many examples as possible, and leverage the Hugo docs code shortcode. If you are unable to add examples but would like to solicit help from the Hugo community, add needsexample: true to your front matter.

Adding to the Showcase

Once you have cloned the Hugo repository, you can add your Hugo website as a new showcase content file via the following command. Name the markdown file accordingly:

hugo new tutorials/my-hugo-showcase-website.md

The archetype for the showcase content type is as follows:

archetypes/showcase.md
---
description: ""
lastmod: ""
license: ""
licenseLink: ""
sitelink: ""
sourcelink: ""
categories: [showcase]
tags: []
image: ""
toc: false
notesforauthors: "Go to gohugo.io/contribute/documentation for more info"
---

Showcase Required Fields

sitelink
the full URL to your website.
title
the <title> of your website.
description
a general description of your website, preferably < 180 characters.
image
the image (filename only) you want to associate with your website on the Showcase page. The image should be 450px × 300px.

We also appreciate the addition of the remaining fields, especially sourcelink and license if you are willing to share your hard work with the open-source community. tags is optional, but we recommend adding at least 2 to 3 tags to improve discoverability.

Add an Image for the Showcase

Youl will need to create a thumbnail of your website. Give your thumbnail a name like my-hugo-site-name.jpg. Save it under docs/static/images/showcase/.

Adding a New Tutorial

Once you have cloned the Hugo repository, you can create a new tutorial via the following command. Name the markdown file accordingly:

hugo new tutorials/my-new-tutorial.md

The archetype for the tutorials content type is as follows:

archetypes/tutorials.md
---
linktitle: ""
description: ""
godocref: ""
publishdate: ""
lastmod: ""
categories: [tutorials]
tags: []
author: ""
authorurl: ""
originalurl: ""
draft: false
aliases: []
notesforauthors: "Go to gohugo.io/contribute/documentation for more info."
---


Adding Code Blocks

Code blocks are crucial for providing examples of Hugo’s new features to end users of the Hugo docs. Whenever possible, create examples that you think Hugo users will be able to implement in their own projects.

Standard Syntax

Across all pages on the Hugo docs, the typical triple-back-tick markdown syntax is used. If you do not want to take the extra time to implement the following code block shortcodes, please use standard Github-flavored markdown. The Hugo docs use a version of highlight.js that’s been modified for specific Hugo keywords.

Your options for languages are xml/html, go/golang, md/markdown/mkd, handlebars, apache, toml, yaml, json, css, asciidoc, ruby, powershell/ps, scss, sh/zsh/bash/git, http/https, and javascript/js.

```html
<h1>Hello world!</h1>
```

Code Block Shortcode

The Hugo documentation comes with a very robust shortcode for adding interactive code blocks.

code

code is the Hugo docs shortcode you’ll use most often. code requires has only one named parameter: file. Here is the pattern:

{{% code file="smart/file/name/with/path.html" download="download.html" copy="true" %}}
```language
A whole bunch of coding going on up in here!
```
{{% /code %}}

The following are the arguments passed into code:

file
the only required argument. file is needed for styling but also plays an important role in helping users create a mental model around Hugo’s directory structure. Visually, this will be displayed as text in the top left of the code block.
download
if omitted, this will have no effect on the rendered shortcode. When a value is added to download, it’s used as the filename for a downloadable version of the code block.
copy
a copy button is added automatically to all code shortcodes. If you want to keep the filename and styling of code but don’t want to encourage readers to copy the code (e.g., a “Do not do” snippet in a tutorial), use copy="false".

Example code Input

This example HTML code block tells Hugo users the following:

  1. This file could live in layouts/_default, as demonstrated by layouts/_default/single.html as the value for file.
  2. This snippet is complete enough to be downloaded and implemented in a Hugo project, as demonstrated by download="single.html".
{{% code file="layouts/_default/single.html" download="single.html" %}}
```html
{{ define "main" }}
<main class="main">
    <article class="content">
        <header>
            <h1>{{.Title}}</h1>
            {{with .Params.subtitle}}
            <span class="subtitle">{{.}}</span>
        </header>
        <div class="body-copy">
            {{.Content}}
        </div>
        <aside class="toc">
            {{.TableOfContents}}
        </aside>
    </article>
</main>
{{ end }}
```
{{% /code %}}
Example ‘code’ Display

The output of this example will render to the Hugo docs as follows:

layouts/_default/single.html
{{ define "main" }}
<main class="main">
    <article class="content">
        <header>
            <h1>{{.Title}}</h1>
            {{with .Params.subtitle}}
            <span class="subtitle">{{.}}</span>
        </header>
        <div class="body-copy">
            {{.Content}}
        </div>
        <aside class="toc">
            {{.TableOfContents}}
        </aside>
    </article>
</main>
{{ end }}

Blockquotes

Blockquotes can be added to the Hugo documentation using typical Markdown blockquote syntax:

> Without the threat of punishment, there is no joy in flight.

The preceding blockquote will render as follows in the Hugo docs:

Without the threat of punishment, there is no joy in flight.

However, you can add a quick and easy <cite> element (added on the client via JavaScript) by separating your main blockquote and the citation with a hyphen with a single space on each side:

> Without the threat of punishment, there is no joy in flight. - [Kobo Abe](https://en.wikipedia.org/wiki/Kobo_Abe)

Which will render as follows in the Hugo docs:

Without the threat of punishment, there is no joy in flight. - Kobo Abe

Admonitions

Admonitions are common in technical documentation. The most popular is that seen in reStructuredText Directives. From the SourceForge documentation:

Admonitions are specially marked “topics” that can appear anywhere an ordinary body element can. They contain arbitrary body elements. Typically, an admonition is rendered as an offset block in a document, sometimes outlined or shaded, with a title matching the admonition type. - SourceForge

The Hugo docs contain three admonitions: note, tip, and warning.

note Admonition

Use the note shortcode when you want to draw attention to information subtly. note is intended to be less of an interruption in content than is warning.

Example note Input

note-with-heading.md
{{% note %}}
Here is a piece of information I would like to draw your **attention** to.
{{% /note %}}

Example note Output

note-with-heading.html
<aside class="admonition note">
	<div class="note-icon">
		<svg id="exclamation-icon" width="100%" height="100%" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:1.41421;">
    <path d="M0,0L24,0L24,24L0,24L0,0Z" style="fill:none;"/>
    <g transform="matrix(1.2,0,0,1.2,-2.4,-2.4)">
        <path d="M12,2C6.48,2 2,6.48 2,12C2,17.52 6.48,22 12,22C17.52,22 22,17.52 22,12C22,6.48 17.52,2 12,2ZM13,17L11,17L11,15L13,15L13,17ZM13,13L11,13L11,7L13,7L13,13Z" style="fill-rule:nonzero;"/>
    </g>
</svg>

	</div>
	
	
	<div class="admonition-content"><p>Here is a piece of information I would like to draw your <strong>attention</strong> to.</p>
</div>
</aside>

Example note Display

tip Admonition

Use the tip shortcode when you want to give the reader advice. tip, like note, is intended to be less of an interruption in content than is warning.

Example tip Input

using-tip.md
{{% tip %}}
Here's a bit of advice to improve your productivity with Hugo.
{{% /tip %}}

Example tip Output

tip-output.html
<aside class="admonition tip">
	<div class="tip-icon">
		<svg id="exclamation-icon" width="100%" height="100%" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:1.41421;">
    <path d="M0,0L24,0L24,24L0,24L0,0Z" style="fill:none;"/>
    <g transform="matrix(1.2,0,0,1.2,-2.4,-2.4)">
        <path d="M12,2C6.48,2 2,6.48 2,12C2,17.52 6.48,22 12,22C17.52,22 22,17.52 22,12C22,6.48 17.52,2 12,2ZM13,17L11,17L11,15L13,15L13,17ZM13,13L11,13L11,7L13,7L13,13Z" style="fill-rule:nonzero;"/>
    </g>
</svg>

	</div>
	
	
	<div class="admonition-content"><p>Here&rsquo;s a bit of advice to improve your productivity with Hugo.</p>
</div>
</aside>

Example tip Display

warning Admonition

Use the warning shortcode when you want to draw the user’s attention to something important. A good usage example is for articulating breaking changes in Hugo versions, known bugs, or templating “gotchas.”

Example warning Input

warning-admonition-input.md
{{% warning %}}
This is a warning, which should be reserved for *important* information like breaking changes.
{{% /warning %}}

Example warning Output

warning-admonition-output.html
<aside class="admonition warning">
	<div class="admonition-icon">
		<svg id="exclamation-icon" width="100%" height="100%" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:1.41421;">
    <path d="M0,0L24,0L24,24L0,24L0,0Z" style="fill:none;"/>
    <g transform="matrix(1.2,0,0,1.2,-2.4,-2.4)">
        <path d="M12,2C6.48,2 2,6.48 2,12C2,17.52 6.48,22 12,22C17.52,22 22,17.52 22,12C22,6.48 17.52,2 12,2ZM13,17L11,17L11,15L13,15L13,17ZM13,13L11,13L11,7L13,7L13,13Z" style="fill-rule:nonzero;"/>
    </g>
</svg>

	</div>
	
	
	<div class="admonition-content"><p>This is a warning, which should be reserved for <em>important</em> information like breaking changes.</p>
</div>
</aside>

Example warning Display

Ask for Code Examples

Sometimes you want to contribute to the docs but don’t have enough time to provide lengthy examples. If you want to flag a piece of content as needing more examples, add the following field to your front matter:

needsexamples: true

Places to Start

The preceding needsexamples field is used to generate the following list of flagged content. Links will take you directly to the edit URL for the file within the GitHub GUI in the event that you are not comfortable cloning and editing the repository locally.

Last Updated: 2017-02-01