Doc Helpers ✍️

The following chapters show important pieces how to use this Hugo template for writing the XLT documentation. Please refer always back to the source code and check how each component is written.

Info Boxes

Just a blockquote. You can still use them. They are kinda boring.

Keyboard

You can reference keyboard keys in text, using the kbd shortcode.

Code

Java Code

Plain

import foo;

public class Foo
{
}

Bash Code

foo@picard $./start.sh

Footnotes

That's some text with a footnote.[^1]

[^1]: And that's the footnote.

That’s some text with a footnote.¹

Links

Any link that is up or down the hierarchy

Go to Load Testing.

Go to XTC.

Go to Release Notes.

(Actually you can build links to wherever in the hierarchy without a shortcode, just like this or this. However the relref shortcode should be preferred as Hugo will perform link validation for all links generated by that shortcode and log a warning or fail the build with an error depending on the configuration.)

Heads up: the Release Notes section uses a setting to generate permalinks from their title instead of their file name (e.g., the link will be release-notes\5.7.x instead of release-notes\5_7_x). You can link these either like this using the relref shortcode or like this in simple markdown without validation.

External links

You can build external links by using the link markdown with complete URLs, Hugo will take care to add target="_blank" to all outgoing links (starting with http*).

Images

An image that gets its source from src and is linked to large if this is given. Paths are relative to static/images/. The .Inner part is the caption.

Another image that is not linked to anything. If it is too wide for the window, it will be scaled by CSS (.img-fluid, .td-content img {max-width: 100%}).

To just use CSS scaling like above for your large image, but think it looks nicer in the text at less than 100% width, you can just pass a max-width parameter to the shortcode that will be included in the image CSS.

Yet another image. Note how neatly you can navigate between the large versions of all images of this page.

Another image using the imageres shortcode, which will resize images to a smaller preview using hugo’s image processing. For this, the source image must be part of the page resources (pages are in a folder as index.md, images in same folder). The .Inner part is the caption.

Colored Text

Should you need colored text, use ctext in green or any other html compatible color code. If none is given, this defaults to grey .

XTC Permissions

Several XTC actions require certain user roles to be performed, either in project or organization context. Use this shortcode to quickly add the necessary role:

{{% permission type="project" role="reader" action="chew gum" %}}

There is no inner part required for this shortcode. The parameters “type” and “action” are optional, the default looks like this:

{{% permission role="reader" %}}

TODO

To-Do Marker

To remind us that something needs to be done, it introduces a marked TODO at the position of the shortcode {{< TODO / >}}. TODO markers right now assume to be in the beginning because they make a little room on the right side - “”.

Optionally you can pass the parameter comment and provide some more information such as {{< TODO comment="More information in the title" / >}}.

Marked Text

{{< TODO >}}To mark some text use this.{{< /TODO >}}

Markdown in a To-Do

{{% TODO %}}To use **markdown** in the to-do, use this.{{% /TODO %}}

To use markdown in the to-do, use this.