Additional Page Elements

Examples of various markdown and Hugo page elements.
Tags:

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.

As this site is deployed to environments with no internet connect 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.

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

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

  • 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

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)

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

{{< 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/.

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

  • A feed is something you should know about, and so are streams .

    A {{< glossary "feed" >}} is something you should know about, and so are {{< glossary "stream" "streams" >}}.

The argument to the shortcode is the glossary term. 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.

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>
```

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:

  1. username - The username to appear in the prompt, defaults to user.
  2. hostname - The hostname to appear in the prompt, defaults to localhost.
  3. 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/past the muli-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 

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

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 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 */

Alerts

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

Warning block Quote

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

The markdown for this is:

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

See also block Quote

Useful for linking to other areas of the documentation or to external sites.

The markdown for this is:

{{% see-also %}}
[Note block quote]({{< relref "#note-block-quote" >}})  
[Warning block quote]({{< relref "#warning-block-quote" >}})
{{% /see-also %}}

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

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

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.

Last modified November 6, 2024: Add section on ancestor folder visibility (44d28df)