How To Write Documentation ✍️

The Xceptance Documentation is based on Docsy. Docsy is a Hugo theme for technical documentation sets, providing simple navigation, site structure, and more. For details on software requirements and build instructions, please refer to the README.

The following chapters demonstrate the key components and best practices for writing XLT documentation with this Hugo template. We recommend always referring back to the source code to see how each component is implemented. While Xceptance has enhanced the Docsy theme with specialized features for XLT, your existing knowledge of Docsy and Hugo will provide a solid foundation.

Contributing

We welcome your help in improving the XLT documentation. For a step-by-step guide on how to fork the repository, run a local build, and submit a pull request, please refer to the How to Contribute section in our README.

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

To build links that are up or down the hierarchy, use the relref shortcode.

• Go to Manual.
• Go to XTC.
• Go to Release Notes.

Go to [Load Testing]({{< relref "load-testing" >}}).
Go to [XTC]({{< relref "xtc" >}}).
Go to [Release Notes]({{< relref "../release-notes" >}}).

Actually you can build links to wherever in the hierarchy without a shortcode, just like this or this.

[just like this](/load-testing) or [this](../../load-testing)

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.

If you don’t want a shadow around your image, you can pass the parameter shadow="false".

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.

The imageres shortcode also supports the shadow="false" parameter to disable the shadow.

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 currently should be placed at the beginning of a line or paragraph as they include extra spacing on the right - “”.

Optionally, you can pass the comment parameter to provide 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.