The page that you are currently viewing is for an old version of Stroom (Legacy). The documentation for the latest version of Stroom (7.6) can be found using the version drop-down at the top of the screen or by clicking here.

Additional Page Elements

Examples of various markdown and Hugo page elements.

Links

Links can be added using either standard markdown link syntax or using a Hugo shortcode. The advantage of the shortcode is that hugo will check for broken links when building the site so there are preferred.

Links to external sites, i.e. on the internet, should have (external link) appended to the link title. This makes it clear to readers which links are local and which are external and therefore possibly not available if there is no access to the internet.

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.

Shortcode 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 "../../../docs/proxy/install.md#prerequisites" >}})

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

To create a link to download a file, like this , that is served by this site you need to do:

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

Paths are relative to /assets/files/.

Code

Inline code

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 separate 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.

Rendered

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

Markdown

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

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 timezone 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 highlighing 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
python
regex
scss
sql
text
toml
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 file you must included 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 */

Alerts

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 %}}

Page level info

This is some info that can contain markdown.

The markdown for this is:

{{% pageinfo %}}
This is some info that can contain **markdown**.
{{% /pageinfo %}}

TODO block Quote

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 there use should be avoided.

Last modified November 26, 2024: Make font paths relative (4afb976)