Stroom – style

Community: Documentation Style Guide

Mon, 01 Jan 0001 00:00:00 +0000

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.

Language

For consistency, the documentation should be written in English (i.e. British English).

For example, the word color is not allowed by the spell checker, if used in normal text. If you need to refer to the CSS property then surround it with back ticks or use it in a code block, .e.g.

Set the CSS property `color` to `red`.

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.

UltiSnips (for Vim)

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

JSON (VS Code)

{
  "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"
  }
}

TODO

Add section on naming, i.e. what names we use for things, e.g. data/meta/stream, config/properties, job/task, etc.

Community: Additional Page Elements

Tue, 20 Jul 2021 00:00:00 +0000

Links

While links can be added using standard markdown link syntax you should use Hugo shortcodes to add them. The advantage of the shortcode is that Hugo will check for broken links when building the site.

External links

As this site is deployed to environments with no internet connection and is also released in PDF form it is important that any links to locations outside of the this site (i.e. on the internet) are clearly marked. To include an external link do the following:

This is a link to Stroom on Github with a title.

This is a link to {{< external-link "Stroom on Github" "https://github.com/gchq/stroom" >}} with a title.

This is the same link with no title, https://github.com/gchq/stroom .

This is the same link with no title, {{< external-link "https://github.com/gchq/stroom" >}}.

Versioned URLs

Some external links are to other Stroom URLs are versioned. If you need to link to a site external to this one that has the Stroom version in the URL then you can use the tag @@VERSION@@ in the URL. This will be translated into the Stroom version of this site, as seen in the Stroom Version (…) drop down at the top of the page. This saves you from having to update the URL on each release of Stroom.

This is a versioned URL https://gchq.github.io/stroom/v7.12

This is a versioned URL {{< external-link "https://gchq.github.io/stroom/v@@VERSION@@" >}}

Warning

This will not work for version legacy as that is not an actual Stroom version.

Anchors

You can link to headings on a page using its anchor. The anchor for a heading is the heading text with:

All non-alphanumeric characters removed
Spaces replaced with a -
All characters made lower case
Multiple consecutive - characters, e.g. --- are replaced with a single -

For example the heading Mr O'Neil's 1st Event (something) becomes as an anchor #mr-oneils-1st-event-something.

See The link examples below that use anchors.

Duplicate anchors

If you have two headings on the same page then Hugo will suffix the anchors with a sequential number to ensure uniqueness of the anchor. For example, with the following markdown:

## Apples

### Example

## Oranges

### Example

Hugo will create the following anchors:

apples
example
oranges
example-1

If you want to avoid confusion and removed the risk of anchors breaking if new headings are added in the middle, then you can explicitly name anchors:

## Apples

### Example {#apples-example}

## Oranges

### Example {#oranges-example}

This is only worth doing if you want to link to these headings.

Shortcode internal page link examples

Shortcode links are slightly more verbose to type but are preferable to markdown style links as the link target will be checked at site build time so you know all the links are correct.

Hugo has ref and relref link shortcodes. Use only relref as this will be translated into a relative path when the site it built ensuring that the site can be run from any base path.

The following are some example of different links to internal content.

Heading anchor

A link to a heading anchor on this page.
```
[link]({{< relref "#alerts" >}})
```

Absolute path

A link to a heading anchor on another page, using an absolute path.

[link]({{< relref "community/documentation/style-guide/using-images#captions" >}})

Relative path

A link to a heading anchor on page above this one, using a relative path.
```
[link]({{< relref "../versions" >}})
```

Unique page name

A link to a heading anchor on another page, using only the unique page name. This is quicker to type and won’t break if pages are moved but will not work if the page name is not unique.
```
[link]({{< relref "running#basic-configuration" >}})
```

Section link

A link to a branch/section in the document tree, i.e. to the \_index.md.
```
[link]({{< relref "docs/HOWTOs" >}})
```

Next page in section link

A link to the next page in the current section. If the current page is the last page in the section then no link will be displayed. What the next page is is defined by the page weights or the default ordering of pages in the section.

This is useful when you have a set of pages in a section that have a natural flow, e.g. where the pages in a section are the sequential steps in an installation guide.

The link looks like this(with the page title in the link text and the hover tip showing both the page title and the description):
Next page - Images
```
{{< next-page >}}
```

Previous page in section link

A link to the previous page in the current section. If the current page is the last page in the section then no link will be displayed. What the previous page is is defined by the page weights or the default ordering of pages in the section.

This is useful when you have a set of pages in a section that have a natural flow, e.g. where the pages in a section are the sequential steps in an installation guide.

The link looks like this(with the page title in the link text and the hover tip showing both the page title and the description):
Previous page - Markdown Style Conventions
```
{{< prev-page >}}
```

Markdown page link examples

Warning

Don’t use markdown style links for internal page links as they can’t be verified at site build time like the short code links can.

Markdown style links should not contain the .md extension as this will be stripped when the site is generated, e.g. for the following content:

/content
   /en
      /docs
         /section-x
            /sub-section-a
               _index.md
               page1.md
               page2.md
            /sub-section-b
               _index.md
               page1.md
               page2.md

This will become:

/docs
   /section-x
      /sub-section-a
         /page1
         /page2
      /sub-section-b
         /page1
         /page2

in the rendered site.

A link to a heading anchor on this page.
```
[link](#alerts)
```
A link to a heading anchor on another page, using a relative link.
```
[link](../using-images#captions)
```
A link to a heading anchor on another page, using an absolute link.
```
[link](/docs/style-guide/using-images#captions)
```

Download file links

You can create a link to download a file, like these:

Download a file .
Download mock_stroom_data.csv

{{< file-link "quick-start-guide/mock_stroom_data.csv" >}}Link Title{{< /file-link >}}

{{< file-link "quick-start-guide/mock_stroom_data.csv" />}}

All paths are relative to /assets/files/.

Glossary links

If you need to create a link to an item in the Glossary you can use the glossary shortcode.

Arguments:

term - The glossary term. This must match the front matter title in the glossary page, e.g. Stream Type. This is case-insensitive.
display_text - Optional. The text to display in line, e.g. Feeds if referring to something plural. If this argument is not supplied, the page title will be displayed in-line.

Examples:

A Feed Feed A Feed is a means of organising and categorising data in Stroom. A Feed contains multiple Streams of data that have been ingested into Stroom or output by a Pipeline. Typically a Feed will contain Streams of data that are all from one system and have a common data format.Click to see more details... is something you should know about, and so are Streams Stream A Stream is the unit of data that Stroom works with and will typically contain many Events.Click to see more details....
```
A {{< glossary "feed" >}} is something you should know about, and so are {{< glossary "stream" "Streams" >}}.
```

The argument to the shortcode is the glossary term (c. This should match the heading text on the Glossary page exactly, ignoring case. It will be converted to an HTML anchor so that you can link directly to the heading for the term in question.

Creating a Glossary Entry

To create a glossary entry, create a file like this:

---
title: "Example Term"
linkTitle: "Example"
description: >
  A short description of the term that will be shown in the tooltip.
  Simple inline _markdown_ only, **no** bullets or shortcodes.
---

Optional additional detail about the term that can contain all markdown and shortcodes.

{{% see-also %}}
* {{< glossary "Another Term" >}}
* {{< glossary "And Another Term" >}}
{{% /see-also %}}

title - Will be used as the tooltip title and inline text (unless overridden).
linkTitle - If title is quite long, use an abbreviated form for the sidebar menus.
description - This will form the content of the tooltip so don’t make it too long. Simple inline markdown only, no bullets or shortcodes. Line breaks are ignored.

The file name must be of the form glossary-xxx.md, where xxx is the page title in anchor form, e.g. glossary-example-term.

Place the file in the directory content/en/docs/glossary/X/ where X is the letter of the alphabet corresponding to the first letter of the first word of the term, e.g. content/en/docs/glossary/e/.

Code

Inline code

When you need to include chunks of code, filenames, or input/output values in-line in text, e.g. config.yml, you can surround it with single backticks.

Rendered

Inline code looks like this.

Markdown

Inline code `looks like this`.

Code blocks (simple)

Code blocks should be surrounded with fences ```language-type and ``` with the language type always specified to ensure correct syntax highlighting. If the language type is not supplied then styling will be different to fenced blocks with a language.

This is a markdown example of a fenced code block containing XML content.

Rendered

<root>
  <child attr="xxx">some val</child>
</root>

Markdown

```xml
<root>
  <child attr="xxx">some val</child>
</root>
```

Note

The fenced code block MUST have a language specified. This ensures the correct default styling is used and makes it explicitly clear to anyone editing the markdown what the content of the block is. If the content of the fenced block has no supported language or is just plain text then use language text.

The following are some example of rendered code blocks:

Plain Text

id,date,time
1,6/2/2018,10:18
2,12/6/2017,5:58
3,6/7/2018,11:58

YAML

---
root:
  someKey: "value"

XML

<root>
  <child attr="xxx">
    some val
  </child>
</root>

bash

echo "${VAR}"

code blocks (advanced)

If you need to show line numbers or to highlight sections of a code block then you can use the code-block shortcode. This shortcode takes the following named arguments:

language - The language for syntax highlighting. Defaults to text.
lines - Whether to display line numbers or not (true|false). Defaults to true.
highlight - A comma-separated list of lines to highlight. Ranges of line numbers can be specified, e.g. 2-8,13,25-30. Defaults to no line highlighting.
start - The line number to start at. Defaults to 1.

The following is an example of how to use the shortcode.

{{< code-block language="xml" highlight="2-5,8" >}}
<root>
  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
</root>
{{< /code-block >}}

Default behaviour

{{< code-block >}}
...
{{< /code-block >}}

<root>
  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
</root>

With line numbers, a language and a starting line number

{{< code-block language="xml" start="5" >}}
...
{{< /code-block >}}

  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
</root>

With line numbers, a language and highlighted lines

{{< code-block language="xml" highlight="2-5,8" >}}
...
{{< /code-block >}}

<root>
  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
</root>

With a language and highlighted lines, but without line numbers

{{< code-block language="xml" lines="false" highlight="2-5,8" >}}
...
{{< /code-block >}}

<root>
  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
  <child attr="xxx">
    some val
  </child>
</root>

Command line blocks

To demonstrate commands being run on the command line you can use the command-line shortcode. This results in a code block with the shell prompt displayed on the left of each line. It also means the prompt part is not selectable when the user selects the text for copy/pasting.

The shortcode takes the following positional arguments:

username - The username to appear in the prompt, defaults to user.
hostname - The hostname to appear in the prompt, defaults to localhost.
language - The language of the content (a valid and installed prism language name language name), defaults to bash.

If you want to display shell output then prefix each output line with (out). It will then be displayed without a prompt. To display a blank line with no prompt then have a line with just (out) in it.

If your shell command is very long then you can split it into multiple lines using the shell line continuation character \ which must be the last character on the line. If this character is present then it will be rendered with a different prompt to indicate it is a continuation. Readers can then copy/paste the multi-line command into a shell and run it.

Rendered

echo hello \
world
(out)hello world
id
(out)uid=1000(david) gid=1000(david)

Markdown

{{< command-line "david" "wopr" >}}
echo hello \
world
(out)hello world
id
(out)uid=1000(david) gid=1000(david)
{{</ command-line >}}

MySQL shell blocks

To demonstrate commands being run in a MySQL shell you can use the sql-shell shortcode. This works in a similar way to the command-line shortcode but has a different prompt and no shortcode arguments.

If you want to display shell output then prefix each output line with (out). It will then be displayed without a prompt.

If your sql statement is multi-line, prefix all lines except the first with (con) (for continuation). Continuation lines will be rendered with a continuation prompt (->).

To display a blank line with no prompt then have a line with just (out) in it.

Rendered

" 
    data-filter-output="(out)"
    data-continuation-prompt="->"
    data-filter-continuation="(con)">select *
(con)from token_type
(con)limit 2;
(out)+----+------+
(out)| id | type |
(out)+----+------+
(out)|  1 | user |
(out)|  2 | api  |
(out)+----+------+
(out)2 rows in set (0.00 sec)
(out)
select database();
(out)+------------+
(out)| database() |
(out)+------------+
(out)| stroom     |
(out)+------------+
(out)1 row in set (0.00 sec)

Markdown

{{< sql-shell >}}
select *
(con)from token_type
(con)limit 2;
(con)+----+------+
(con)| id | type |
(con)+----+------+
(con)|  1 | user |
(con)|  2 | api  |
(con)+----+------+
(out)2 rows in set (0.00 sec)
(out)
select database();
(out)+------------+
(out)| database() |
(out)+------------+
(out)| stroom     |
(out)+------------+
(out)1 row in set (0.00 sec)
{{</ sql-shell >}}

Directory Listings

Using the unix tree command you can produce directory listings to use with the treeview code block language.

The following is an example of how to produce the directory tree in ASCII form.

tree -n -F -L 1 --charset=ascii

Rendered

./
|-- ACTIVE_SERVICES.txt
|-- ALL_SERVICES.txt
|-- backup_databases.sh*
|-- certs/
|-- command.sh*
|-- start.sh*
|-- status.sh*
|-- stop.sh*
`-- volumes/

Markdown

```treeview
./
|-- ACTIVE_SERVICES.txt
|-- ALL_SERVICES.txt
|-- backup_databases.sh*
|-- certs/
|-- command.sh*
|-- start.sh*
|-- status.sh*
|-- stop.sh*
`-- volumes/
```

Inline files

Some code or text examples may be too large for a fenced block so you can put the content in a separate file and include it in-line like so.

<?xml version="1.1" encoding="UTF-8"?>
<dataSplitter
    xmlns="data-splitter:3"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="data-splitter:3 file://data-splitter-v3.0.1.xsd"
    version="3.0">
  <!-- 
  GEOHOST REFERENCE FEED:
  
  CHANGE HISTORY
  v1.0.0 - 2020-02-09 John Doe
  
  This is a reference feed for device Logical and Geographic data.
  
  The feed provides for each device
  * the device FQDN
  * the device IP Address
  * the device Country location (using ISO 3166-1 alpha-3 codes)
  * the device Site location
  * the device Building location
  * the device Room location
  *the device TimeZone location (both standard then daylight time zone offsets from UTC)
  
  The data is a TAB delimited file with the first line providing headings.
  
  Example data:
  
  FQDN	IPAddress	Country	Site	Building	Room	TimeZones
stroomnode00.strmdev00.org	192.168.2.245	GBR	Bristol-S00	GZero	R00	+00:00/+01:00
stroomnode01.strmdev01.org	192.168.3.117	AUS	Sydney-S04	R6	5-134	+10:00/+11:00
host01.company4.org	192.168.4.220	USA	LosAngeles-S19	ILM	C5-54-2	-08:00/-07:00
  
  -->
  
  <!-- Match the heading line - split on newline and match a maximum of one line  -->
  <split delimiter="\n" maxMatch="1">
   
   <!-- Store each heading and note we split fields on the TAB (&#9;) character -->
     <group>
       <split delimiter="&#9;">
         <var id="heading"/>
       </split>
     </group>
   </split>
   
  !-- Match all other data lines - splitting on newline -->
  <split delimiter="\n">
    <group>
      <!-- Store each field using the column heading number for each column ($heading$1) and note we split fields on the TAB (&#9;) character -->
       <split delimiter="&#9;">
         <data name="$heading$1" value="$1"/>
       </split>
    </group>
  </split>
</dataSplitter>

Example in-line XML file ( Download in_line_file_example.xml )

The card has a maximum height and will show scrollbars as required.

Examples of how to use in-line files are:

{{< textfile "style-guide/in_line_file_example.xml" "xml" >}}My caption{{< /textfile >}}
{{< textfile "style-guide/in_line_file_example.xml" >}}My caption{{< /textfile >}}
{{< textfile "style-guide/in_line_file_example.xml" />}}

Supported languages

This site uses Prismjs for syntax highlighting code blocks. PrismJs supports a large number of different languages however only certain languages have been included with this site. The language specified in the markdown code fence or in the command-line shortcode must be in the list of included languages.

The list of included language names are:

sh
bash
css
csv
groovy
http
java
javascript
jq
json
properties (Use for Stroom metadata) python
regex
scss
sql
text
toml
treeview
xml
yaml

To include extra languages in this site you need to build a new version of the prism.js and prism.css files. This can be done here . When creating new versions of these files you must include the languages and plugins already included else you may break this site. The generated files are then copied over the top of /static/css/prism.css and /static/js/prism.js. Both files include a comment at the top with the link to the PrismJs download page with the currently included items selected. Use this link then add any additional items, bearing in mind the size of the download and its impact on page load times.

An example of the download link is https://prismjs.com/download.html#themes=prism&languages=markup+css+clike+javascript+bash+csv+groovy+java+jq+json+markdown+python+regex+scss+sql+toml+yaml&plugins=line-highlight+line-numbers+command-line+toolbar+copy-to-clipboard+treeview */

Warning

The css/js downloaded from the Prism site is taken from the head of their master branch so even though the css/js mention a Prism version number this may be the same for downloads done at different times.

Alerts

Various page/block level quotes for drawing attention to things.

Warning

Using shortcodes, e.g. {{< pipe-elm "SplitFilter" >}} inside an of these alerts is currently not fully supported so may not work.

Warning block Quote

Warning

This is a warning that can contain markdown.

The markdown for this is:

{{% warning %}}
This is a warning that can contain _markdown_.
{{% /warning %}}

Page level warning

Warning

This is a warning that can contain markdown.

The markdown for this is:

{{% page-warning %}}
This is a warning that can contain _markdown_.
{{% /page-warning %}}

Note block Quote

Note

This is a note that can contain markdown.

The markdown for this is:

{{% note %}}
This is a note that can contain **markdown**.
{{% /note %}}

TODO block Quote

Used to indicate areas of the documentation that are unfinished or incorrect.

TODO

This is a TODO that can contain markdown.

The markdown for this is:

{{% todo %}}
This is a TODO that can contain `markdown`.
{{% /todo %}}

Cards

Cards can be used to display related content side by side. Each card can contain markdown and/or Hugo short codes. The cards will be displayed horizontally to fill the width of the page.

YAML

---
root:
  someKey: "value"

XML

<root>
  <child attr="xxx">some val</child>
</root>

The markdown for this is:

{{< cardpane >}}
  {{< card header="YAML" >}}
```yaml
---
root:
  someKey: "value"
```
  {{< /card >}}
  {{< card header="XML" >}}
```xml
<root>
  <child attr="xxx">some val</child>
</root>
```
  {{< /card >}}
{{< /cardpane >}}

Tabbed panes

Hugo/Docsy have shortcodes for tabbed panes however these mean only one tab will be printed or visible in the generated PDF so their use should be avoided.

Community: Images

Mon, 01 Jan 0001 00:00:00 +0000

Image assets

All Images should be placed in /assets/images/ or within a descendent directory of it. Images should be added to the markdown using the image shortcode. This ensures a consistent look for all images and allows control of the size of the image.

The short code can be added in the following ways.

Markdown:

{{< image "style-guide/stroom-oo.svg" "200x" >}}

{{< image "style-guide/stroom-oo.png" >}}

{{< image "style-guide/stroom-oo.svg" "200x" >}}Image caption{{< /image >}}

All paths used in the image shortcode are relative to /assets/images.

The following shows an example of the directory structure.


/assets
   /images
      /section-x
         /sub-section-y
            /page1
               /image.svg
/content
   /en
      /docs
         /section-x
            /sub-section-y
               page1.md - #image shortcode used in here

Where images are only used by one page then the directory structure in /assets ought to mirror that of the page the images are used in, as shown above. If images are used by multiple pages then some other sensible organisation of the images should be used, e.g. /assets/images/section-x if they are limited to pages in one section, or /assets/images/common if they are used in multiple sections.

Captions

The image can be displayed with a caption:

Example:

By W3C SVG Logo, CC BY-SA 4.0, https://commons.wikimedia.org/w/index.php?curid=105996438

Markdown:

{{< image "style-guide/svg-logo.svg" "200x" >}}
By W3C SVG Logo, CC BY-SA 4.0, https://commons.wikimedia.org/w/index.php?curid=105996438
{{< /image >}}

Size

The image can be defined with a maximum width (e.g. "300x") or a maximum height ("x200").

Example:

Markdown:

{{< image "style-guide/svg-logo.svg" "120x" />}}

.png files

.png files can be rendered in their original size by omitting the size argument.

Examples:

Or they can be rendered with a set size.

Markdown:

The markdown for the examples above is:

{{< image "style-guide/stroom-amber.png" />}}

Or they can be rendered with a set size.

{{< image "style-guide/stroom-amber.png" "50x"/>}}

Using global `/assets/` resources

For images that are shared by multiple page bundles, e.g. stroom icons, place them in /assets/images/. The image path is relative to /assets/images/, e.g. file /assets/images/style-guide/svg-example.svg becomes style-guide/svg-example.svg.

Example:

This is some optional caption text for the image. And this is another line.

Markdown:

{{< image "style-guide/svg-example.svg" "200x" >}}
This is some optional caption text for the image.
And this is another line.
{{< /image >}}

PlantUML

PlantUML is the favoured tool for producing diagrams such as UML diagrams, entity relationship diagrams and other more general architecture diagrams. The diagrams are written in plain text which makes them easy to version control. The plantUML syntax can then be converted into image files, e.g. .svg files.

A plantUML diagram looks like this in plain text form:

@startuml
Alice -> Bob: Authentication Request
Bob --> Alice: Authentication Response

Alice -> Bob: Another authentication Request
Alice <-- Bob: Another authentication Response
@enduml

PlantUML diagrams should be saved in a dedicated .puml file in the same folder as the page that will display it. If it is needed by multiple pages then it should be saved in /assets/images/.

The build process will convert all .puml files to a corresponding .puml.svg file. These generated .puml.svg files are ignored by git so need to be regenerated at build time or when you change a .puml file. The images can be generated by doing:

./container_build/runInPumlDocker.sh SVG

You should embed a PlantUML image like this, using the .puml.svg file (that may not yet exist, but will have to exist before the site is built):

Example:

Markdown:

{{< image "style-guide/puml-example.puml.svg" "300x" />}}

Using page resources

Images can be located in a page bundle . This is where the page is defined as a named directory (rather than a .md file) with an associated index.md file for the markdown content. All other items in the directory are page resources that can be used by the page, i.e. image files.

Warning

Whilst you can structure your site using page resources the preferred approach for stroom-docs is to use the common assets directory. This keeps all the images in one place and means pages can have a named markdown file rather than all being called index.md.

Use the image short code to display an image file that is located in the same directory as the page. For the short code to work the page must be a leaf bundle (index.md) or a branch bundle (_index.md), i.e:

/docs
   /MyPage
      index.md - #image shortcode used in here
      example.svg

/docs
   /MySection
      /Page1
         index.md
      /Page2
         index.md
      _index.md - #image shortcode used in here
      example.svg

In the above example, the shortcode would look like:

{{< image "example.svg" "200x" >}}

Stroom user interface Components

Sometimes it is useful to display an image of certain user interface elements to explain something. Rather than use screenshots which are very difficult to keep up to date, you can instead use some simple shortcodes to display some UI elements, e.g. buttons, pipeline elements, etc. By using shortcodes, any change to the look of the Stroom UI means only the shortcode content and their styling need to change, without having to recreate tens or hundreds of screenshots.

Stroom icons

Stroom UI icons such as or can be added in line using the shortcode stroom-icon.

Arguments:

name - The filename (and relative path) of the icon file. The path is relative to /assets/images/stroom-ui/, e.g. documents/Feed.svg.
title (optional) - The hover tip title that will be given to the icon. If not supplied, the filename (minus extension) will be converted to sentence case and used as the title.
enabled (optional) [enabled|disabled] - Whether the button is enabled or disabled. Defaults to enabled.
colour (optional) - The colour variant to use for the icon. Not all icons support colour variants. If not supplied, and where the icon supports colour variants, then the default colour is blue. See below for the list of colour variants.

The full list of available icons can be found in the Icon Gallery.

Warning

The icon filenames and paths are case sensitive so ensure you have the correct case, e.g. most document icons are in upper sentence case.

Examples:

Simple use:

Custom hover tip name:

A document icon:

A pipeline icon:

Enabled vs disabled

An icon in its different colour states:

Default (no colour specified)
blue
brey
green
red

Markdown:

The markdown for the examples above is:

Simple use: {{< stroom-icon "save.svg" >}}

Custom hover tip name: {{< stroom-icon "key.svg" "Not a key" >}}

A document icon: {{< stroom-icon "document/Feed.svg" >}}

A pipeline icon: {{< stroom-icon "pipeline/text.svg" >}}

Enabled {{< stroom-icon "delete.svg" >}} vs disabled {{< stroom-icon "delete.svg" "Delete" "disabled" >}}

An icon in its different colour states:
* Default (no colour specified) {{< stroom-icon name="settings.svg" >}}
* `blue` {{< stroom-icon name="settings.svg" colour="blue" >}}
* `brey` {{< stroom-icon name="settings.svg" colour="grey" >}}
* `green` {{< stroom-icon name="settings.svg" colour="green" >}}
* `red` {{< stroom-icon name="settings.svg" colour="red" >}}

Buttons

To display a user interface button you can use the shortcode stroom-btn with the button title as its only argument.

Arguments:

title - The text to display on the button.
type - Optional. (primary|secondary).
- primary results in a blue button.
- secondary results in a red button.
- Not Set results in a standard grey button.
filename - Optional. Filename of an icon to use next to the text, e.g. undo.svg.

Note

If the title is OK, Close or Cancel then the type and filename do not need to be set as they will be set automatically.

Examples:

OK , Close , Cancel , New and Undo

And not in line

Save

Markdown:

The markdown for the examples above is:

{{< stroom-btn "Ok" >}}, {{< stroom-btn "Close" >}}, {{< stroom-btn "Cancel" >}} and {{< stroom-btn title="Undo" filename="undo.svg" >}}

And not in line

{{< stroom-btn "Save" >}}<br/>

Document Links

To display a reference to a Stroom document type, e.g. XSL Translation with associated icon you can use the stroom-doc short code. It will render as the document type name and associated icon. Both will be a clickable link to the appropriate section of the Document Reference.

Arguments:

type - The type of the document (case in-sensitive), e.g. ElasticIndex, feed, etc. See Document Type Icons for the full list (use the file name without extension).
show_icon - Whether to show the icon or not (true or false). Default value is true.

Examples:

A Feed , a XSL Translation and an Git Repo .

This is one without an icon Pipeline .

Markdown:

The markdown for the examples above is:

A {{< stroom-doc "feed" >}}, a {{< stroom-doc "XSLT" >}} and an {{< stroom-doc "gitrepo" >}}.

This is one without an icon {{< stroom-doc type="Pipeline" show_icon="false" >}}.

Pipeline elements

To display a pipeline element (as seen on the Structure sub-tab on the Pipeline screen), like SplitFilter , you can use the shortcode pipe-elm.

Arguments:

element_name - The name of the pipeline element (case sensitive), e.g. XSLTFilter.
display_name (optional) - The display name for the pipeline element. If a display name is not provided then the element name will be used as the display name.

The list of available pipeline elements can be found in this gallery. An invalid element_name will result in an error when building the site.

The icon will be selected to match the element name provided. The element is a clickable link to the appropriate reference page for that element.

Examples:

This is an xsltFilter with its default name:

XSLTFilter

This is a splitFilter with a custom name:

My Split Filter

This is an IndexingFilter in line.

Markdown:

The markdown for the examples above is:

This is an xsltFilter with its default name:

{{< pipe-elm "XSLTFilter" >}}<br/>

This is a splitFilter with a custom name:

{{< pipe-elm "SplitFilter" "My Split Filter" >}}<br/>

This is an {{< pipe-elm "IndexingFilter" >}} in line.

Pipelines

To display a pipeline consisting of multiple pipeline elements (as seen on the Structure sub-tab on the Pipeline screen) you can use the short code pipe.

This shortcode takes no arguments. Instead, the inner content of the shortcode is populated with multiple pipe-elm shortcodes to describe each of the elements in the pipeline. This shortcode does not support any branching/forking in the pipeline.

Example:

Source

XMLParser

recordCount (read)

SplitFilter

IdEnrichmentFilter

XSLTFilter

SchemaFilter

ElasticIndexingFilter

recordCount (written)

Markdown:

The markdown for the two examples above is:

{{< pipe >}}
  {{< pipe-elm "Source" >}}
  {{< pipe-elm "XMLParser" >}}
  {{< pipe-elm "RecordCountFilter" "recordCount (read)" >}}
  {{< pipe-elm "SplitFilter" >}}
  {{< pipe-elm "IdEnrichmentFilter" >}}
  {{< pipe-elm "XSLTFilter" >}}
  {{< pipe-elm "SchemaFilter" >}}
  {{< pipe-elm "ElasticIndexingFilter" >}}
  {{< pipe-elm "RecordCountFilter" "recordCount (written)" >}}
{{< /pipe >}}

Each element is a clickable link to the appropriate reference page for that element. Pipelines cannot be used in-line in text.

For details on how to use pipe-elm see pipeline elements above. The list of available pipeline elements can be found in this gallery.

Stroom document tabs

To display a top level Stroom document tab, like Big Index , you can use the shortcode stroom-tab.

Arguments:

icon_filename - The filename of the icon to use (relative to assets/images/stroom-ui/document/) (case sensitive), e.g. Pipeline.svg.
title - The text to display in the tab, e.g. Indexing Pipeline.
state (optional) - Whether the tab is active or not (active or inactive). Defaults to inactive.

For a full list of all available icons see the Icon Gallery

Examples:

Simple: MY_FEED

Custom name: My Translation

Active/Inactive: My Translation My Translation

Unsaved: * My Translation

Markdown:

The markdown for these examples is:

Simple: {{< stroom-tab "Feed.svg" "MY_FEED" >}}
Custom name: {{< stroom-tab "XSLT.svg" "My Translation" >}}
Active/Inactive: {{< stroom-tab "XSLT.svg" "My Translation" "active" >}} {{< stroom-tab "XSLT.svg" "My Translation" >}}
Unsaved: {{< stroom-tab "XSLT.svg" "My Translation" "active" "unsaved" >}}

To display the selection of a menu item you can use the stroom-menu shortcode.

Arguments:

menu_item_names... - One argument per menu item name in the order root to leaf.

Examples:

For example to demonstrate creating a folder using the context menu:

The shortcode takes one argument per menu item so you can have multiple levels of menu.

Markdown:

The markdown for these examples is:

For example to demonstrate creating a folder using the context menu:

{{< stroom-menu "New" "Folder" >}}

The shortcode takes one argument per menu item so you can have multiple levels of menu.

{{< stroom-menu "Add" "Folder" "Feed" >}}

It cannot be used in-line in text, it needs to be on its own line.

The list of available menu items with an icon can be found in this gallery. Menu item names are case-sensitive.

If the menu item name is not an exact match to one in the gallery then it will be displayed without an icon, e.g.:

Keyboard Shortcuts

To display a keyboard shortcut (AKA key binding) you can use the key-bind shortcode.

Arguments:

key_bind... - One or more key bindings, with keys in the key binding delimited by ,, - or +. The name and case of non-alphabet keys will be normalised, e.g. del => Delete. The modifier keys ctrl, shift, alt, meta will be placed first and displayed in a consistent order.

Each argument is one of more keys that are pressed at the same time, e.g. "ctrl,c" for Ctrl ^ + c . Chord key bindings where multiple key binds are pressed and released in sequence have one argument for each step in the chord, e.g. pressing g then p has arguments "g" and "p", producing g , p .

Examples:

This is a key binding with modifiers Ctrl ^ + Shift ⇧ + f and this is chord type key binding g , p .

If the key is a , then use + or - as the delimiter, e.g. Ctrl ^ + Alt + , , Ctrl ^ + + or Alt + - .

Markdown:

The markdown for these examples is:

This is a key binding with modifiers {{< key-bind "ctrl,shift,f" >}}  and this is chord type key binding {{< key-bind "g" "p" >}}.

If the key is a `,` then use `+` or `-` as the delimiter, e.g. {{< key-bind "ctrl+alt+," >}}, {{< key-bind "ctrl,+" >}} or {{< key-bind "alt+-" >}}.

Explorer Tree

To render a section of the Stroom explorer tree you can use the stroom-tree and stroom-tree-doc short codes.

Arguments:

stroom-tree
- name - The name of the folder. If name is System, it will render with the System icon.
- text - Optional text to place next to the folder. This text can be used to explain the purpose of the folder.
stroom-tree-doc
- type - The document type. This is the name of the icon file for the document type without the .svg extension, e.g. Feed. See Document type icons for the full list of type names.
- name - The name of the folder. If name is System, it will render with the System icon.
- text - Optional text to place next to the folder. This text can be used to explain the purpose of the folder.

If the stroom-tree short code has no inner content it will be rendered as a closed folder (e.g. SUB_SYSTEM-X1 in the example).

Examples:

A tree that includes the System root.

System

Configuration

My DictionarySome descriptive text

Feeds

SYSTEM-X

SUB_SYSTEM-X1A closed folder

SUB_SYSTEM-X2An open folder

SUB_SYSTEM-X2

A sub-tree that doesn’t include the System root.

Configuration

My DictionarySome descriptive text

Markdown:

The markdown for this examples is:

{{< stroom-tree "System" >}}
  {{< stroom-tree "Configuration" >}}
    {{< stroom-tree-doc "Dictionary" "My Dictionary" "Some descriptive text" >}}
  {{< /stroom-tree >}}
  {{< stroom-tree "Feeds" >}}
    {{< stroom-tree "SYSTEM-X" >}}
      {{< stroom-tree "SUB_SYSTEM-X1" "A closed folder" />}}
      {{< stroom-tree "SUB_SYSTEM-X2" "An open folder" >}}
        {{< stroom-tree-doc "Feed" "SUB_SYSTEM-X2" >}}
        {{< stroom-tree-doc "Pipeline" "SUB_SYSTEM-X2" >}}
        {{< stroom-tree-doc "TextConverter" "SUB_SYSTEM-X2" >}}
        {{< stroom-tree-doc "XSLT" "SUB_SYSTEM-X2" >}}
      {{< /stroom-tree >}}
    {{< /stroom-tree >}}
  {{< /stroom-tree >}}
{{< /stroom-tree >}}

{{< stroom-tree "Configuration" >}}
  {{< stroom-tree-doc "Dictionary" "My Dictionary" "Some descriptive text" >}}
{{< /stroom-tree >}}

Stroom – style

Community: Documentation Style Guide

Overview

Language

Shortcodes

Editor snippets and shortcodes

TODO

Community: Additional Page Elements

Links

External links

Versioned URLs

Warning

Anchors

Duplicate anchors

Shortcode internal page link examples

Heading anchor

Absolute path

Relative path

Unique page name

Section link

Next page in section link

Previous page in section link

Markdown page link examples

Warning

Download file links

Glossary links

Creating a Glossary Entry

Code

Inline code

Code blocks (simple)

Note

code blocks (advanced)

Command line blocks

MySQL shell blocks

Directory Listings

Inline files

Supported languages

Warning

Alerts

Warning

Warning block Quote

Warning

Page level warning

Warning

Note block Quote

Note

See also block Quote

See Also

Page level info

TODO block Quote

TODO

Cards

Tabbed panes

Community: Images

Image assets

Captions

Size

.png files

Using global /assets/ resources

PlantUML

Using page resources

Warning

Stroom user interface Components

Stroom icons

Warning

Buttons

Note

Document Links

Pipeline elements

Pipelines

Stroom document tabs

Stroom selected menu items

Keyboard Shortcuts

Explorer Tree

Using global `/assets/` resources