About the transformer tool

The transformer tool generates Killercoda tutorials from Grafana documentation source files.

To use the transformer tool, you need to add Killercoda metadata to the source file front matter and annotate your source file with Killercoda directives.

Metadata

You specify Killercoda tutorial metadata in the source file front matter as the value for the killercoda field. The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial.

Field	Type	Description
`killercoda.backend.imageid`	String	The name of the Killercoda environment's backend image. Supported values include `ubuntu`.
`killercoda.description`	String	The description displayed on the Killercoda website
`killercoda.details.finish.text`	String	The filename of the finish page Markdown source in the `grafana/killercoda` repository. A finish directive in the documentation source overrides this.
`killercoda.details.intro.text`	String	The filename of the introduction page Markdown source in the `grafana/killercoda` repository. An intro directive in the documentation source overrides this.
`killercoda.preprocessing.substitutions`	Array	Substitute matches of a regular expression with a replacement. For more information, refer to Substitutions.
`killercoda.title`	String	The title for the tutorial on the Killercoda website.

The following YAML demonstrates a number of the fields:

killercoda:
  preprocessing:
    substitutions:
      - regexp: evaluate-loki-([^-]+)-
        replacement: evaluate-loki_${1}_
  title: Loki Quickstart Demo
  description: This sandbox provides an online enviroment for testing the Loki quickstart demo.
  details:
    finish:
      text: finish.md
  backend:
    imageid: ubuntu

Substitutions

Substitutions substitutes all matches of a regular expression in a source file with a replacement. Each substitution has two fields:

regexp: An RE2 regular expression matched and replacement.
replacement: The string that replaces the match. You can reference numbered capture groups using the $ syntax. To reference the first capture group, use $1.

Directives

Directives in the source file modify how the transformer tool generates the tutorial. You write directives in the source file with HTML comments.

Use directives to:

Configure executable code blocks
Define pages
Ignore parts of the documentation

Exec

Exec directives tell the transform tool to make the contained fenced code block executable.

The start marker is:

<!-- INTERACTIVE exec START -->

The end marker is:

<!-- INTERACTIVE exec END -->

Note

By default, the tool makes bash fenced code blocks executable so you don't need  directives for bash code blocks. You can override this behavior with the  directives which take precedence over the default behavior.

Examples

<!-- INTERACTIVE exec START -->

```bash
echo 'Hello, world!'
```

<!-- INTERACTIVE exec END -->

Produces:

```bash
echo 'Hello, world!'
```{{exec}}

Copy

Copy directives tell the transform tool to make the contained fenced code block copyable.

The start marker is:

<!-- INTERACTIVE copy START -->

The end marker is:

<!-- INTERACTIVE copy END -->

Note

By default, the tool makes all fenced code blocks other than bash copyable so you don't need  directives for those code blocks. You can override this behavior with the  directives which take precedence over the default behavior.

Examples

<!-- INTERACTIVE copy START -->

```bash
echo 'Hello, world!'
```

<!-- INTERACTIVE copy END -->

Produces:

```bash
echo 'Hello, world!'
```{{copy}}

Ignore

The ignore directive tells the transform tool to skip the contents within the markers when generating the Killercoda page.

The start marker is:

<!-- INTERACTIVE ignore START -->

The end marker is:

<!-- INTERACTIVE ignore END -->

To do the inverse task, and ignore content in the website build, use the docs/ignore shortcode.

Examples

Information common to both pages.

<!-- INTERACTIVE ignore START -->

Information unique to the Grafana website page.

<!-- INTERACTIVE ignore END -->

Produces:

Information common to both pages.

Page

The page directive tells the transform tool to use the content between the markers as the source for a Killercoda page. The page's filename is the first argument to the directive.

Every tutorial must have at least the pages:

intro.md: An introduction to the tutorial.
step1.md: The first step in the tutorial.
finish.md: A closing page that summarizes steps taken and includes next steps.

You can also add additional steps using the step<N>.md, where <N> is in the range 2-20. Steps must be sequential, you can't have step1.md and step3.md without a step2.md.

The start marker is:

<!-- INTERACTIVE page <FILENAME> START -->

The end marker is:

<!-- INTERACTIVE page <FILENAME> END -->

Transformations

The Grafana documentation source uses some syntax that isn't supported by Killercoda. The transformer tool transforms some Grafana documentation syntax into equivalent Killercoda Markdown.

The transformer tool transforms the following syntax:

`admonition` shortcode

The tool transforms the admonition shortcode into a blockquote.

The following Grafana documentation source:

{{< admonition type="<TYPE>" >}}
<FIRST PARAGRAPH>

<SECOND PARAGRAPH>
{{< /admontion >}}

becomes the following Killercoda Markdown:

> **<TYPE>**:
> <FIRST PARAGRAPH>
>
> <SECOND PARAGRAPH>

`figure` shortcode

The tool transforms the figure shortcode into an inline Markdown image.

The following Grafana documentation source:

{{< figure src="<URL>" alt="<ALT TEXT" >}}

becomes the following Killercoda Markdown:

![<ALT TEXT](URL)

Generate a tutorial

You can generate a new tutorial from existing documentation using the transformer tool. After generation, a GitHub Actions workflow updates the tutorial when the documentation source changes.

Before you begin

Clone the repository with the source documentation.
Clone the Killercoda repository.
Download and install Go to run the transformer tool.

To generate a tutorial:

In the source repository, create a branch.

Give the branch a name that reflects the planned changes. For example, 2024-06-killercoda-tutorial-for-loki-quickstart.
In the Killercoda repository, create a branch.

For convenience, name the branch the same as you did in the source repository.
In the source repository, run make docs from the docs/ directory so that you can verify your changes don't break the rendered documentation.
In the source file, add the Killercoda metadata to the front matter.

Front matter is YAML metadata written before the page's content. For more information, refer to the Hugo front matter documentation.

For an example Killercoda front matter, refer to Metadata.
Configure an introduction page.

Use one of the two options:
1. In the source repository, add the page directives with the intro.md argument.
  
  The start marker is  and the end marker is .
2. 1. In the Killercoda repository, add a intro.md file in the output tutorial directory.
  2. In the source file, add the killercoda.details.intro.text field with the value intro.md.
Add page directives for each step in the tutorial.

You must include at least one step. The first step uses the start marker  and the end marker .
Configure a finish page.

Use one of the two options:
1. In the source repository, add the page directives with the finish.md argument.
  
  The start marker is  and the end marker is .
2. 1. In the Killercoda repository, add a finish.md file in the output tutorial directory.
  2. In the source file, add the killercoda.details.finish.text field with the value finish.md.
Generate the tutorial.
1. In the Killercoda repository, change to the tools/transformer directory.
2. Run go run ./ <PATH TO SOURCE FILE> <PATH TO OUTPUT DIRECTORY>
  - <PATH TO SOURCE FILE> is the path to the documentation file.
    
    For example, ~/ext/grafana/loki/docs/sources/get-started/quick-start.md.
  - <PATH TO OUTPUT DIRECTORY> is the path to the output directory in the Killercoda repository.
    
    For example, ~/ext/grafana/killercoda/loki/loki-quickstart.
  The tool creates the index.json and step Markdown files.
Add the tutorial to the Killercoda structure file.

The structure file is a structure.json file in each directory that contains tutorials.

The Loki structure file is loki/structure.json.
In each repository, commit your changes, push your branch, and open a pull request.
A Killercoda maintainer reviews the PR to ensure that the generate tutorial works as expected.

Add foreground and background scripts

Foreground and background scripts are shell scripts that run during the introduction and finish pages of a tutorial. The scripts are useful for setting up the environment for the tutorial and cleaning up after the tutorial.

Scripts are another asset that you must maintain, so use them sparingly. A good example of using a script is to update the Docker Compose package before running the tutorial.

Use foreground scripts when you want to the user to see the script output. Use background scripts when you want to hide the output of the script.

Create your script

Since these scripts are primarily used for preparing the interactive environment, they're stored within the sandbox tutorial in the Killercoda repository. Make sure to run the transformer first to create your tutorial before adding your script in this generated tutorial directory.

Here is an example of a script that updates the Docker Compose package:

#!/bin/sh

set -euf
# shellcheck disable=SC3040
(set -o pipefail 2> /dev/null) && set -o pipefail


sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

ARCH="$(dpkg --print-architecture)"
VERSION_CODENAME="$(source /etc/os-release && echo "${VERSION_CODENAME}")"
readonly ARCH VERSION_CODENAME

printf 'deb [arch=%s signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu %s stable' "${ARCH}" "${VERSION_CODENAME}" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt-get update
sudo apt-get install -y docker-compose-plugin && clear && echo "Setup complete. You may now begin the tutorial."

Tip

Add a message at the end of the script to inform the user that the setup is complete. Due to an issue with how Killercoda runs the script, the script after apt-get install isn't run. A work around is to use && <NEXT COMMAND> to force the script to continue.

Add the script to the tutorial

To add the script to the tutorial, you need to add the script to the killercoda metadata in the source file.

Note

The transformer tool only supports foreground and background scripts for the introduction and finish pages.

The following example sets the foreground script for the introduction page to be docker-compose-update.sh:

title: Quick start for Tempo
menuTitle: Quick start for Tempo
description: Use Docker to quickly view traces using K-6 and Tempo
weight: 600
killercoda:
  title: Quick start for Tempo
  description: Use Docker to quickly view traces using K-6 and Tempo
  details:
    intro:
      foreground: docker-compose-update.sh
  backend:
    imageid: ubuntu

The following example sets the foreground script for the introduction page to be docker-compose-cleanup.sh:

title: Quick start for Tempo
menuTitle: Quick start for Tempo
description: Use Docker to quickly view traces using K-6 and Tempo
weight: 600
killercoda:
  title: Quick start for Tempo
  description: Use Docker to quickly view traces using K-6 and Tempo
  details:
    finish:
      background: docker-compose-cleanup.sh
  backend:
    imageid: ubuntu

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

transformer.md

transformer.md

About the transformer tool

Metadata

Substitutions

Directives

Exec

Examples

Copy

Examples

Ignore

Examples

Page

Transformations

`admonition` shortcode

`figure` shortcode

Generate a tutorial

Before you begin

Add foreground and background scripts

Create your script

Add the script to the tutorial

Files

transformer.md

Latest commit

History

transformer.md

File metadata and controls

About the transformer tool

Metadata

Substitutions

Directives

Exec

Examples

Copy

Examples

Ignore

Examples

Page

Transformations

admonition shortcode

figure shortcode

Generate a tutorial

Before you begin

Add foreground and background scripts

Create your script

Add the script to the tutorial

`admonition` shortcode

`figure` shortcode