Authoring documentation

How do write and edits the docs in this site.

Filesystem organization

Each page is a Hugo page bundle , a directory with a index.md and any attachments/images used in the page.

Pages can be nested to create a hierarchical structure. If a directory contains multiple pages, the index.md must be prefixed with an underscore (_index.md) to tell Hugo to recurse into the directory for additional pages. Example:

.
└── content
    ├── _index.md <- https://example.com/
    ├── intro
    |   └── index.md <- https://example.com/intro/
    ├── how-to
    |   ├── _index.md <- https://example.com/how-to/
    |   ├── start
    |   |   └── index.md <- https://example.com/how-to/start/
    |   └── finish
    |       └── index.md <- https://example.com/how-to/finish/
    └── faq
        └── index.md <- https://example.com/faq/

Content markup

Content is formatted as Markdown , with support for many of the more advanced Markdown features, as well as a number of shortcodes supported by Hugo .

Standard Markdown link syntax is preferred

[link text](http://example.com/)

Hugo also provides a shortcode that can be used to make it easier to link to pages within the site:

[Quick Start →]({{< relref "intro" >}})

Images

Small images can be embedded using normal Markdown syntax, but Hugo also provides a {{< figure >}} shortcode ideal for embedding larger images with more metadata.

For either syntax, the image should be committed in the directory with the page it appears on, and identified in the front matter resources object:

resources:
  - src: demo-figure.jpg

Markdown syntax for small images 

![This kitten icon](demo-img.png)

Output:

This kitten icon

This adorable kitten icon used as a demo img was downloaded from The Noun Project .

Figure shortcode for large images 

{{< figure src="demo-figure.jpg" caption="This adorable kitten used as the demo figure was [downloaded from Unsplash](https://unsplash.com/photos/tuomgxdoIP4)." >}}

All available options documented here .

Output:

This adorable kitten used as the demo figure was downloaded from Unsplash.

This adorable kitten used as the demo figure was downloaded from Unsplash.

Video

Many modern browsers accept videos in the img element (via the {{< figure >}} shortcode, for example), but embedding YouTube or Vimeo videos is most compatible.

YouTube

For a given YouTube URL such as https://www.youtube.com/watch?v=w7Ft2ymGmfc, the YouTube shortcode should be:

{{< youtube w7Ft2ymGmfc >}}

Output:

Vimeo

For a given Vimeo URL such as https://vimeo.com/channels/staffpicks/146022717, the Vimeo shortcode should be:

{{< vimeo 146022717 >}}

Output:

Code

Standard code fencing with single and triple backticks works as expected. Hugo also supports code highlighting with the following shortcode:

{{< highlight html >}}
<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
    {{ range .Pages }}
        {{ .Render "summary"}}
    {{ end }}
  </div>
</section>
{{< /highlight >}}

Output:

<section id="main">
  <div>
   <h1 id="title">{{ .Title }}</h1>
    {{ range .Pages }}
        {{ .Render "summary"}}
    {{ end }}
  </div>
</section>

In-page emphasis 

{{< alert icon="👉" text="The Alert shortcode should be used sparingly." >}}

Output:

Table of contents structure

The left column table of contents follows the hierarchy set by the filesystem directory structure, but the order of pages at any given level is based on page weight set in the front matter of the page. By default, all pages are ordered by : Weight > Date > LinkTitle > FilePath.

See weight: 900 in the front matter in the source of this page as an example.

Page headings

The right column table of contents follows the order of the headings in the doc.

Styleguide

Sentence case

All headings in these docs should follow sentence case as described in this APA guide .

Edit this page on GitHub

← Contact support