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 are a compact way of inserting reusable content into a page and make it easy to change how a page element is styled by just changing the shortcode in one place.

There are numerous shortcodes available to use:

• Hugo built in shortcodes
• Docsy theme shortcodes
• Bespoke stroom-docs shortcodes. These can be found in layouts/shortcodes/.

An example of using a short code in your markdown is:

Click the {{< stroom-icon "save.svg" "Save Document" >}} icon.

This calls the shortcode stroom-icon with the positional arguments save.svg and Save Document. Shortcodes can either use positional arguments or named arguments depending on how they have been written.

This is an example of calling a shortcode with named arguments:

Click the {{< stroom-icon name="settings.svg" colour="red" >}} icon.

Check the documentation for specific shortcode to see how to call it.

Editor snippets and shortcodes

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

For example the following UltiSnips (for Vim) and VS Code snippets 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"
  }
}