Product Docs Hugo Conventions

Implementation and Customization

Product Docs Repository README

The README contains information on content management, like how to use various archetypes, automated content generation, and the product IA.

github.com

Mermaid Diagrams

How to create Mermaid diagrams

Front Matter

Front matter conventions and custom front matter that supports certain layouts and other functionality.

Menus

How the left menu and breadcrumb menus work.

Shortcodes

Custom shortcodes for use in content.

Conventions

Internal Links

Use relrefs to link to other pages within product docs so Hugo will throw errors when our internal links don’t work.

• Omit file extensions.

• Use relative paths for links to pages whenever possible (when the page identifier is unique). For example, instead of using /volumes/how-to/unmount, use unmount. This takes advantage of Hugo’s page lookup and avoids needing to update a lot of relrefs if we move a page.

• When using absolute paths, begin the path with a leading /, as in /droplets/quickstart, not droplets/quickstart. Hugo searches for pages starting at the root when you begin the path with /, and searches relative to the current page when you omit it.

Anchor Links

Every Markdown header automatically produces an ID tag, which you can use in anchor links. However, these tags are based on the text of the header, meaning the link changes if the text of the header changes.

You can specify a stable anchor link after the header. Anchor link names should be short and descriptive.

## Alpha 101 {#alpha}

Lorem ipsum dolor sit amet ...

## Version 1.0 {#version-1-dot-0}

Morem mipsum molor mit mamet ...

See Hugo’s documentation on anchor links for more information.