Hugo Constructs

Cumulus Networks uses Hugo to create a static web site for our user documentation. This topic describes some of the features of Hugo that impact how our documentation is created and presented.

If you want to provide feedback or submit new content for inclusion in our documentation, please refer to the other topics in this document.

Directory Structure

Hugo uses a directory structure to support multilevel content, images, templates and the so forth. The highest-level directories include:

  • archetypes
  • content
  • data
  • resources
  • static
  • themes

Their roles and content are described here:

DirectoryDescription
archetypesContains template files for new content (.md files). Populates and adds default front matter. Works by calling hugo new to build the Markdown files.
contentContains all of the sections and page resources built into the main site. The arrangement of this content determines the structure and hierarchy of the final site.
dataContains all .JSON, .YAML, and .TOML files Hugo uses for formatting and displaying content. Hugo indexes this directory and it is accessible through templates.
resourcesContains files generated by Hugo. Two subdirectories, assets and images, contain the files. Assets contains .js and .scss files used by Hugo templates. These are not published to the static site unless piped in by templates.
staticContains all static files, including configuration files, user-created images, and PDFs. These are the files used in the published site.
themesContains the document themes used to display the content in the published site. The theme lookup order is defined in config.toml. Cumulus uses the Book theme as the base theme, which is added as a git submodule. A subdirectory, layouts, contains the go-html templates (.html files) that build pages from content. Hugo will search for templates in this folder before looking in themes.

Modifying files in any other directory will have significant impact on the overall appearance and functioning of the site, so please file a bug to request changes to the site.

Front Matter

Each page in Hugo contains a .YAML front matter header. For example.

---
title: 802.1X Interfaces
author: Cumulus Networks
weight: 101
aliases:
 - /display/DOCS/802.1X+Interfaces
 - /pages/viewpage.action?pageId=8363046
pageID: 8363046
product: Cumulus Linux
version: 3.7
imgData: cumulus-linux
siteSlug: cumulus-linux
---

Hugo uses these parameters in the generation of the site. The Cumulus Networks documentation team use these to set the order of display within a topic, link to images,and place the content with the correct product and release. When you create a new Markdown file, these values are provided. In this case, please provide a title and then let the documentation team modify any of the other parameters as needed.

When creating a new file, a draft parameter is added to the front matter that is set to true. This prevents the file from being published before the content is complete. The documentation team will change it to false when it is ready for publication.

Graphical Content

Cumulus Networks makes use of graphical content by placing static images in the /static/images/ directory. Images in this directory are accessible by the published site and well as the Hugo server used to display content locally.

Markdown is designed for speed and simplicity, therefore limited in authoring and customizing rendered content. Rather than insert raw HTML into markdown, Hugo provides shortcodes, or predefined templates, that can be called from Markdown content for situations where you need additional information or formatting capabilities.

Hugo provides several built-in shortcodes, of which a subset are useful for documentation. For reference, the full Hugo documentation for all of their built-in shortcodes is located here. We use the built-in figure shortcode and a custom img (image) shortcode to display figures and icons. They are described here.

We do not use the ref and relref shortcodes for hyperlinks and references, but instead use inline Markdown. Refer to the Markdown Guide for details about adding references.

Image Shortcode

The img, or image, shortcode is a custom shortcode. It is used when you want to insert an icon or small image inline with your text. Note that you do not need to include the static/ portion of the path to the file. Optionally, images can be scaled using the width and/or height parameters, specified in pixels. Using only width or height scales the image proportionally. Images that are too wide to be included inline are automatically presented on a new line. The basic shortcode is:

{{<img src = “/path/">}}

For example:

{{<img src = “/images/icons/export-button.png” width="80”>}}

{{<img src = “/images/cumulus-linux/evpn-basic-clos.png” width="700”>}}

Figure Shortcode

The figure shortcode is a built-in Hugo shortcode. It is used when you want to insert an image on a new line. This shortcode makes use of the HTML <figure> element, wrapping the <img> tag and providing more optional parameters to specify how the image is displayed. The basic shortcode is:

{{<figure src=”/path/">}}

The available parameters include:

ParameterDescription
srcURL of image to be displayed
linkURL of hyperlink destination
altAlternative text if image cannot be displayed
titleImage Title, placed above figure
captionImage Caption, placed below figure
heightHeight of image, in pixels
widthWidth of image, in pixels

For example:

{{<figure src=”/images/netq/sch-trace-result-small-card.png” alt="Results of a scheduled trace shown in the small card” caption="Scheduled Trace Result” width="200px”>}}

{{<figure src = “/images/cumulus-linux/evpn-basic-clos.png” width="700”>}}