Documentation Style Guide

Overview

Stroom’s documentation is created using the static site generator Hugo . This converts markdown content into a rich HTML site. The markdown content in stroom-docs is not intended to be read as-is in GitHub, it needs to be rendered first.

The full documentation for Hugo can be found here . The site also uses the Docsy theme for Hugo. The documentation for Docsy can be found here . The Docsy theme provides a lot of the styling but also adds other features and shortcodes. You should consult the Docsy documentation in the first instance.

To maintain a degree of consistency in the documentation you should use this section as a reference for how to layout your content.

Shortcodes

The documentation makes heavy use of Hugo shortcodes for adding page elements such as links, icons, images, etc. Shortcodes make it easy to change how a page element is styled by just changing the shortcode.

Hugo includes many shortcodes , the Docsy theme adds some more and there are some bespoke stroom-docs ones in layouts/shortcodes/.

To make your life easier when editing the documentation it is highly recomended to use an editor that supports text snippets. Snippets make it very quick to add shortcodes into the documentation.

For example the following snippet adds a skeleton front matter to a page.

snippet hfront "Hugo markdown metadata front matter" b
---
title: "${1:Title}"
linkTitle: "$1"
#weight:
date: `date "+%Y-%m-%d"`
tags: $2
description: >
  $3
---

$0
endsnippet

{
  "hugo-front-matter": {
    "prefix": "hfront",
    "body": [
      "---",
      "title: \"${1:Title}\"",
      "linkTitle: \"$1\"",
      "#weight:",
      "date: `date \"+%Y-%m-%d\"`",
      "tags: $2",
      "description: >",
      "  $3",
      "---",
      "",
      "$0"
    ],
    "description": "Hugo markdown metadata front matter"
  }
}