docs: further guidelines around adding extra scripts and assets

README.md

@@ -1,5 +1,12 @@
 # Killercoda - Grafana Labs Tutorials
 
+<p >
+<a href="https://github.com/grafana/killercoda/actions/workflows/regenerate-tutorials.yml">
+    <img src="https://github.com/grafana/killercoda/actions/workflows/regenerate-tutorials.yml/badge.svg?branch=staging" alt="Regenerate Tutorials">
+</a>
+</p>
+
+
 Welcome to the Grafana Labs tutorials repository.
 This repository contains interactive tutorials for Grafana Labs, hosted on [Killercoda](https://killercoda.com/grafana-labs/).
 These tutorials aim to help users understand and implement Grafana solutions without the need to download or install the software.
@@ -39,6 +46,10 @@ We welcome contributions to enhance these tutorials.
 
 ### Propose changes
 
+> **Note:**
+> Use the following contribution steps if you want to create a tutorial that's not also part of Grafana Labs documentation.
+> Otherwise follow these [steps](./docs/transformer.md#generate-a-tutorial) to generate a tutorial from that documentation.
+
 1. Fork the repository by clicking on the **Fork** button on the top right corner of this page.
 
    For more information, refer to [Fork a repository](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).

docs/transformer.md

@@ -18,6 +18,7 @@ The tool uses the metadata to perform preprocessing on the source file and gener
 | `killercoda.preprocessing.substitutions` | Array  | Substitute matches of a regular expression with a replacement. For more information, refer to [Substitutions](#substitutions).                                       |
 | `killercoda.title`                       | String | The title for the tutorial on the Killercoda website.                                                                                                                |
 
+
 The following YAML demonstrates a number of the fields:
 
 ```yaml
@@ -335,3 +336,64 @@ To generate a tutorial:
 1. In each repository, commit your changes, push your branch, and open a pull request.
 
 1. A Killercoda maintainer reviews the PR to ensure that the generate tutorial works as expected.
+
+## Scripts and extra course files
+
+If your tutorial requires scripts or extra files, make sure to manually add them to the tutorial directory in the Killercoda repository. For example, if your tutorial requires a script to run:
+
+1. Add the bash script to the tutorial directory in the Killercoda repository. Refer to the [what-is-loki](../loki/what-is-loki/) tutorial for an example.
+2. Add the script to the desired step within the `index.json` file. Note that `foreground` scripts run in the foreground (seen in terminal), and `background` scripts run in the background (run in background thread). For example:
+   ```json
+   {
+      "title": "What is Loki?",
+      "description": "A sandbox enviroment to introduce Loki to new users.",
+      "details": {
+         "intro": {
+         "text": "intro.md",
+         "foreground": "script1.sh"
+         },
+         "steps": [
+         {
+            "text": "step1.md",
+            "foreground": "script2.sh"
+         }
+         ],
+         "finish": {
+         "text": "finished.md"
+         }
+      },
+      "backend": {
+         "imageid": "ubuntu"
+      }
+   }
+
+   ```
+
+For extra assets, such as images or configuration files:
+1. Create a directory called `assets` in the tutorial directory.
+2. Add the assets to the `assets` directory.
+3. Add the mount path to the `index.json` file:
+   ```json
+   {
+      "title": "Grafana Basics",
+      "description": "In this demo learn how to install and configure Grafana",
+      "details": {
+         "intro": {
+         "text": "intro.md"
+         },
+         "steps": [],
+         "finish": {
+         "text": "finished.md"
+         },
+         "assets": {
+         "host01": [
+            {"file": "*", "target": "/education"}
+         ]
+         }
+      },
+      "backend": {
+         "imageid": "ubuntu"
+      }
+   }
+   ```
+   Refer to the [grafana-basics](../grafana/grafana-basics/index.json) tutorial for an example.