From 8832055916e30f0bdb1767aea20dc82858a6265e Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Fri, 10 Jan 2025 14:05:40 +0000 Subject: [PATCH 01/25] Added new transformer sandbox --- .../sandbox-transformer-walk-through.md | 337 ++++++++++++++++++ loki/loki-quickstart/finish.md | 2 - loki/loki-quickstart/preprocessed.md | 20 +- .../finish.md | 7 + .../index.json | 32 ++ .../sandbox-transformer-walk-through/intro.md | 13 + .../preprocessed.md | 337 ++++++++++++++++++ .../sandbox-transformer-walk-through/step1.md | 45 +++ .../sandbox-transformer-walk-through/step2.md | 21 ++ .../sandbox-transformer-walk-through/step3.md | 117 ++++++ .../sandbox-transformer-walk-through/step4.md | 57 +++ .../sandbox-transformer-walk-through/step5.md | 34 ++ sandbox-developer/structure.json | 5 + 13 files changed, 1024 insertions(+), 3 deletions(-) create mode 100644 docs/examples/sandbox-transformer-walk-through.md create mode 100644 sandbox-developer/sandbox-transformer-walk-through/finish.md create mode 100644 sandbox-developer/sandbox-transformer-walk-through/index.json create mode 100644 sandbox-developer/sandbox-transformer-walk-through/intro.md create mode 100755 sandbox-developer/sandbox-transformer-walk-through/preprocessed.md create mode 100644 sandbox-developer/sandbox-transformer-walk-through/step1.md create mode 100644 sandbox-developer/sandbox-transformer-walk-through/step2.md create mode 100644 sandbox-developer/sandbox-transformer-walk-through/step3.md create mode 100644 sandbox-developer/sandbox-transformer-walk-through/step4.md create mode 100644 sandbox-developer/sandbox-transformer-walk-through/step5.md create mode 100644 sandbox-developer/structure.json diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md new file mode 100644 index 0000000..9fdedd8 --- /dev/null +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -0,0 +1,337 @@ +--- +title: Learn how to use the Sandbox Transformer +menuTitle: Learn how to use the Sandbox Transformer +description: Learn how to use the Sandbox Transformer to turn hugo docs into a course +weight: 250 +killercoda: + title: Learn how to use the Sandbox Transformer + description: Learn how to use the Sandbox Transformer to turn hugo docs into a course + backend: + imageid: ubuntu +--- + + + +# Learn how to use the Sandbox Transformer + +The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into KillerCoda courses. This tool is still in development, but we`re excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. + +> This tutorial will also work with basic Markdown files, however, there are certain Hugo specific features such as the document metadata which is required for the transformer to work. This my interfere with the rendering of the original Markdown file. + +## What you will learn + +- How to build the Sandbox Transformer +- Learn the basic meta syntax +- How to use the Sandbox Transformer to turn Hugo docs into a course + + + + + +# Prerequisites + +In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. + +## Clone the repository + +First, you need to clone the repository to your local machine. You can do this by running the following command: + +```bash +git clone https://github.com/grafana/killercoda.git +``` + +Its best practise to create a new branch for each new course you create. You can do this by running the following command: + +```bash +git checkout -b my-new-course +``` + +## Install Go + +The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: + +1. Download the Go package: + + ```bash + wget https://go.dev/dl/go1.23.4.linux-386.tar.gz + ``` +1. Remove old versions of Go and Install the package: + + ```bash + rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz + ``` + +1. Add the Go binary to your PATH: + + ```bash + export PATH=$PATH:/usr/local/go/bin + ``` +1. Verify the installation: + + ```bash + go version + ``` + + + + + +# Build the Sandbox Transformer + +Now that you have the repository cloned and Go installed, you can build the Sandbox Transformer. + +## Build the transformer + +To build the transformer: + +1. navigate to the `tools/transformer` directory: + + ```bash + cd tools/transformer + ``` + +2. Then run the following command: + + ```bash + go build + ``` + +This will create a binary file called `transformer` in the `tools/transformer` directory. + + + + + +# Learn the basic meta syntax + +The Sandbox Transformer uses a special syntax to define the metadata for the course. This metadata is used to define the structure of the course and the content of each page. + +Here is a breakdown of the basic meta syntax. For more information on the meta syntax, see the [full documentation](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md) + + + +## 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. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) + +The following YAML demonstrates a number of the fields: + +```yaml +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 +``` + +## Directives + +Directives in the source file modify how the transformer tool generates the tutorial. +You write directives in the source file with HTML comments. + +### 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.md`, where _``_ 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: + +```markdown + +``` + +The end marker is: + +```markdown + +``` + +### Exec + +Exec directives tell the transform tool to make the contained fenced code block executable. + +> [!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. + +The start marker is: + +```markdown + +``` + +The end marker is: + +```markdown + +``` + +### Copy + +Copy directives tell the transform tool to make the contained fenced code block copyable. + +The start marker is: + +```markdown + +``` + +The end marker is: + +```markdown + +``` + +### Ignore + +The ignore directive tells the transform tool to skip the contents within the markers when generating the Killercoda page. + +The start marker is: + +```markdown + +``` + +The end marker is: + +```markdown + +``` + +## Examples + +The best place to see how the meta syntax works is to look at the examples in the `docs/examples` directory of the `killercoda` repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. + + + + + +# Use the Sandbox Transformer to create a course + +Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn a Markdown docs into a course. Lets use one of the examples in the `docs/examples` directory of the `killercoda` repository: + +1. Navigate back to the root of the `killercoda` repository: + + ```bash + cd ../.. + ``` +1. Make a new directory for your new courses: + + ```bash + mkdir new-courses + ``` + This is where your courses for a specific topic will live. You can create multiple courses in this directory. + +1. Create a new directory for your course: + + ```bash + mkdir new-courses/new-course-1 + ``` + +1. We will also create a `structure.json` file more on this later: + + ```bash + touch new-courses/structure.json + ``` + +1. Its time to run the transformer on the example course: + + ```bash + ./tools/transformer/transformer docs/examples/complete-docs-example.md new-courses/new-course-1 + ``` + This will transform the `complete-docs-example.md` file into a course in the `new-course-1` directory. + +1. Verify the course was created: + + ```bash + ls new-courses/new-course-1 + ``` + You should see a number of files and directories created for the course. + +1. Finally, add the course to the `structure.json` file: + + ```json + { + "items": [ + { "path": "new-course-1", "title": "New Course 1" } + ] + } + ``` + This will tell Killercoda where to find the course. + + + + + + + +# Testing the course + +Before you open a PR to the `killercoda` repository, you should test the course to make sure it works as expected. The easiest way to do this is to run the course via your own Killercoda instance. To do this follow these steps: + +1. Fork the `killercoda` repository to your own GitHub account. This will provide you with a URL to your forked repository. + ``` + https://github.com//killercoda.git + ``` + +1. Add the forked repository as a remote to your local repository: + + ```bash + git remote add forked https://github.com//killercoda.git + ``` + +1. Add the changes to your forked repository: + + ```bash + git add . + git commit -m "Add new course" + ``` + +1. Push the changes to your forked repository: + + ```bash + git push forked my-new-course + ``` + +1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) + +1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repositor) and add your forked repository. + +1. Once saved, you should see your course in the list of courses. Click on the course to open it. + + + + + +# Conclusion + +In this tutorial, you learned how to use the Sandbox Transformer to turn Markdown docs into a course. You learned how to build the transformer, the basic meta syntax, and how to use the transformer to create a course. You also learned how to test the course using your own Killercoda instance. + +## Next steps + +When you are ready, you can open a PR to the `killercoda` repository to add your course. We are excited to see what you create and to get your feedback on the Sandbox Transformer. + + + + + + + diff --git a/loki/loki-quickstart/finish.md b/loki/loki-quickstart/finish.md index 730defd..3a5f8e5 100644 --- a/loki/loki-quickstart/finish.md +++ b/loki/loki-quickstart/finish.md @@ -6,8 +6,6 @@ You have completed the Loki Quickstart demo. So where to go next? Head back to where you started from to continue with the Loki documentation: [Loki documentation](https://grafana.com/docs/loki/latest/get-started/quick-start/). -# Complete metrics, logs, traces, and profiling example - If you would like to run a demonstration environment that includes Mimir, Loki, Tempo, and Grafana, you can use [Introduction to Metrics, Logs, Traces, and Profiling in Grafana](https://github.com/grafana/intro-to-mlt). It’s a self-contained environment for learning about Mimir, Loki, Tempo, and Grafana. diff --git a/loki/loki-quickstart/preprocessed.md b/loki/loki-quickstart/preprocessed.md index 4b40f62..56931c8 100755 --- a/loki/loki-quickstart/preprocessed.md +++ b/loki/loki-quickstart/preprocessed.md @@ -90,12 +90,31 @@ Before you start, you need to have the following installed on your local system: 2. Download `loki-config.yaml`, `alloy-local-config.yaml`, and `docker-compose.yaml`: + + {{< tabs >}} + {{< tab-content name="wget" >}} ```bash wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/loki-config.yaml -O loki-config.yaml wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/alloy-local-config.yaml -O alloy-local-config.yaml wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/docker-compose.yaml -O docker-compose.yaml ``` + {{< /tab-content >}} + {{< tab-content name="curl" >}} + ```bash + curl https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/loki-config.yaml --output loki-config.yaml + curl https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/alloy-local-config.yaml --output alloy-local-config.yaml + curl https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/docker-compose.yaml --output docker-compose.yaml + ``` + {{< /tab-content >}} + {{< /tabs >}} + + ```bash + wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/loki-config.yaml -O loki-config.yaml + wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/alloy-local-config.yaml -O alloy-local-config.yaml + wget https://raw.githubusercontent.com/grafana/loki/main/examples/getting-started/docker-compose.yaml -O docker-compose.yaml + ``` + 3. Deploy the sample Docker image. With `evaluate-loki` as the current working directory, start the demo environment using `docker compose`: @@ -324,7 +343,6 @@ You have completed the Loki Quickstart demo. So where to go next? ## Back to docs Head back to where you started from to continue with the Loki documentation: [Loki documentation](https://grafana.com/docs/loki/latest/get-started/quick-start/). -## Complete metrics, logs, traces, and profiling example If you would like to run a demonstration environment that includes Mimir, Loki, Tempo, and Grafana, you can use [Introduction to Metrics, Logs, Traces, and Profiling in Grafana](https://github.com/grafana/intro-to-mlt). It's a self-contained environment for learning about Mimir, Loki, Tempo, and Grafana. diff --git a/sandbox-developer/sandbox-transformer-walk-through/finish.md b/sandbox-developer/sandbox-transformer-walk-through/finish.md new file mode 100644 index 0000000..22c8df0 --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/finish.md @@ -0,0 +1,7 @@ +# Conclusion + +In this tutorial, you learned how to use the Sandbox Transformer to turn Markdown docs into a course. You learned how to build the transformer, the basic meta syntax, and how to use the transformer to create a course. You also learned how to test the course using your own Killercoda instance. + +## Next steps + +When you are ready, you can open a PR to the `killercoda`{{copy}} repository to add your course. We are excited to see what you create and to get your feedback on the Sandbox Transformer. diff --git a/sandbox-developer/sandbox-transformer-walk-through/index.json b/sandbox-developer/sandbox-transformer-walk-through/index.json new file mode 100644 index 0000000..c72a6e3 --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/index.json @@ -0,0 +1,32 @@ +{ + "title": "Learn how to use the Sandbox Transformer", + "description": "Learn how to use the Sandbox Transformer to turn hugo docs into a course", + "details": { + "intro": { + "text": "intro.md" + }, + "steps": [ + { + "text": "step1.md" + }, + { + "text": "step2.md" + }, + { + "text": "step3.md" + }, + { + "text": "step4.md" + }, + { + "text": "step5.md" + } + ], + "finish": { + "text": "finish.md" + } + }, + "backend": { + "imageid": "ubuntu" + } +} diff --git a/sandbox-developer/sandbox-transformer-walk-through/intro.md b/sandbox-developer/sandbox-transformer-walk-through/intro.md new file mode 100644 index 0000000..5913c6c --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/intro.md @@ -0,0 +1,13 @@ +# Learn how to use the Sandbox Transformer + +The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into KillerCoda courses. This tool is still in development, but we`re excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. + +> This tutorial will also work with basic Markdown files, however, there are certain Hugo specific features such as the document metadata which is required for the transformer to work. This my interfere with the rendering of the original Markdown file. + +## What you will learn + +- How to build the Sandbox Transformer + +- Learn the basic meta syntax + +- How to use the Sandbox Transformer to turn Hugo docs into a course diff --git a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md new file mode 100755 index 0000000..9fdedd8 --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md @@ -0,0 +1,337 @@ +--- +title: Learn how to use the Sandbox Transformer +menuTitle: Learn how to use the Sandbox Transformer +description: Learn how to use the Sandbox Transformer to turn hugo docs into a course +weight: 250 +killercoda: + title: Learn how to use the Sandbox Transformer + description: Learn how to use the Sandbox Transformer to turn hugo docs into a course + backend: + imageid: ubuntu +--- + + + +# Learn how to use the Sandbox Transformer + +The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into KillerCoda courses. This tool is still in development, but we`re excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. + +> This tutorial will also work with basic Markdown files, however, there are certain Hugo specific features such as the document metadata which is required for the transformer to work. This my interfere with the rendering of the original Markdown file. + +## What you will learn + +- How to build the Sandbox Transformer +- Learn the basic meta syntax +- How to use the Sandbox Transformer to turn Hugo docs into a course + + + + + +# Prerequisites + +In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. + +## Clone the repository + +First, you need to clone the repository to your local machine. You can do this by running the following command: + +```bash +git clone https://github.com/grafana/killercoda.git +``` + +Its best practise to create a new branch for each new course you create. You can do this by running the following command: + +```bash +git checkout -b my-new-course +``` + +## Install Go + +The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: + +1. Download the Go package: + + ```bash + wget https://go.dev/dl/go1.23.4.linux-386.tar.gz + ``` +1. Remove old versions of Go and Install the package: + + ```bash + rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz + ``` + +1. Add the Go binary to your PATH: + + ```bash + export PATH=$PATH:/usr/local/go/bin + ``` +1. Verify the installation: + + ```bash + go version + ``` + + + + + +# Build the Sandbox Transformer + +Now that you have the repository cloned and Go installed, you can build the Sandbox Transformer. + +## Build the transformer + +To build the transformer: + +1. navigate to the `tools/transformer` directory: + + ```bash + cd tools/transformer + ``` + +2. Then run the following command: + + ```bash + go build + ``` + +This will create a binary file called `transformer` in the `tools/transformer` directory. + + + + + +# Learn the basic meta syntax + +The Sandbox Transformer uses a special syntax to define the metadata for the course. This metadata is used to define the structure of the course and the content of each page. + +Here is a breakdown of the basic meta syntax. For more information on the meta syntax, see the [full documentation](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md) + + + +## 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. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) + +The following YAML demonstrates a number of the fields: + +```yaml +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 +``` + +## Directives + +Directives in the source file modify how the transformer tool generates the tutorial. +You write directives in the source file with HTML comments. + +### 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.md`, where _``_ 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: + +```markdown + +``` + +The end marker is: + +```markdown + +``` + +### Exec + +Exec directives tell the transform tool to make the contained fenced code block executable. + +> [!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. + +The start marker is: + +```markdown + +``` + +The end marker is: + +```markdown + +``` + +### Copy + +Copy directives tell the transform tool to make the contained fenced code block copyable. + +The start marker is: + +```markdown + +``` + +The end marker is: + +```markdown + +``` + +### Ignore + +The ignore directive tells the transform tool to skip the contents within the markers when generating the Killercoda page. + +The start marker is: + +```markdown + +``` + +The end marker is: + +```markdown + +``` + +## Examples + +The best place to see how the meta syntax works is to look at the examples in the `docs/examples` directory of the `killercoda` repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. + + + + + +# Use the Sandbox Transformer to create a course + +Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn a Markdown docs into a course. Lets use one of the examples in the `docs/examples` directory of the `killercoda` repository: + +1. Navigate back to the root of the `killercoda` repository: + + ```bash + cd ../.. + ``` +1. Make a new directory for your new courses: + + ```bash + mkdir new-courses + ``` + This is where your courses for a specific topic will live. You can create multiple courses in this directory. + +1. Create a new directory for your course: + + ```bash + mkdir new-courses/new-course-1 + ``` + +1. We will also create a `structure.json` file more on this later: + + ```bash + touch new-courses/structure.json + ``` + +1. Its time to run the transformer on the example course: + + ```bash + ./tools/transformer/transformer docs/examples/complete-docs-example.md new-courses/new-course-1 + ``` + This will transform the `complete-docs-example.md` file into a course in the `new-course-1` directory. + +1. Verify the course was created: + + ```bash + ls new-courses/new-course-1 + ``` + You should see a number of files and directories created for the course. + +1. Finally, add the course to the `structure.json` file: + + ```json + { + "items": [ + { "path": "new-course-1", "title": "New Course 1" } + ] + } + ``` + This will tell Killercoda where to find the course. + + + + + + + +# Testing the course + +Before you open a PR to the `killercoda` repository, you should test the course to make sure it works as expected. The easiest way to do this is to run the course via your own Killercoda instance. To do this follow these steps: + +1. Fork the `killercoda` repository to your own GitHub account. This will provide you with a URL to your forked repository. + ``` + https://github.com//killercoda.git + ``` + +1. Add the forked repository as a remote to your local repository: + + ```bash + git remote add forked https://github.com//killercoda.git + ``` + +1. Add the changes to your forked repository: + + ```bash + git add . + git commit -m "Add new course" + ``` + +1. Push the changes to your forked repository: + + ```bash + git push forked my-new-course + ``` + +1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) + +1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repositor) and add your forked repository. + +1. Once saved, you should see your course in the list of courses. Click on the course to open it. + + + + + +# Conclusion + +In this tutorial, you learned how to use the Sandbox Transformer to turn Markdown docs into a course. You learned how to build the transformer, the basic meta syntax, and how to use the transformer to create a course. You also learned how to test the course using your own Killercoda instance. + +## Next steps + +When you are ready, you can open a PR to the `killercoda` repository to add your course. We are excited to see what you create and to get your feedback on the Sandbox Transformer. + + + + + + + diff --git a/sandbox-developer/sandbox-transformer-walk-through/step1.md b/sandbox-developer/sandbox-transformer-walk-through/step1.md new file mode 100644 index 0000000..53df475 --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/step1.md @@ -0,0 +1,45 @@ +# Prerequisites + +In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. + +## Clone the repository + +First, you need to clone the repository to your local machine. You can do this by running the following command: + +```bash +git clone https://github.com/grafana/killercoda.git +```{{exec}} + +Its best practise to create a new branch for each new course you create. You can do this by running the following command: + +```bash +git checkout -b my-new-course +```{{exec}} + +## Install Go + +The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: + +1. Download the Go package: + + ```bash + wget https://go.dev/dl/go1.23.4.linux-386.tar.gz + ```{{exec}} + +1. Remove old versions of Go and Install the package: + + ```bash + rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz + ```{{exec}} + +1. Add the Go binary to your PATH: + + ```bash + export PATH=$PATH:/usr/local/go/bin + ```{{exec}} + +1. Verify the installation: + + ```bash + go version + ```{{exec}} diff --git a/sandbox-developer/sandbox-transformer-walk-through/step2.md b/sandbox-developer/sandbox-transformer-walk-through/step2.md new file mode 100644 index 0000000..5e46f17 --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/step2.md @@ -0,0 +1,21 @@ +# Build the Sandbox Transformer + +Now that you have the repository cloned and Go installed, you can build the Sandbox Transformer. + +## Build the transformer + +To build the transformer: + +1. navigate to the `tools/transformer`{{copy}} directory: + + ```bash + cd tools/transformer + ```{{exec}} + +1. Then run the following command: + + ```bash + go build + ```{{exec}} + +This will create a binary file called `transformer`{{copy}} in the `tools/transformer`{{copy}} directory. diff --git a/sandbox-developer/sandbox-transformer-walk-through/step3.md b/sandbox-developer/sandbox-transformer-walk-through/step3.md new file mode 100644 index 0000000..1b053c0 --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/step3.md @@ -0,0 +1,117 @@ +# Learn the basic meta syntax + +The Sandbox Transformer uses a special syntax to define the metadata for the course. This metadata is used to define the structure of the course and the content of each page. + +Here is a breakdown of the basic meta syntax. For more information on the meta syntax, see the [full documentation](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md) + +## Metadata + +You specify Killercoda tutorial metadata in the source file front matter as the value for the `killercoda`{{copy}} field. +The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) + +The following YAML demonstrates a number of the fields: + +```yaml +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 +```{{copy}} + +## Directives + +Directives in the source file modify how the transformer tool generates the tutorial. +You write directives in the source file with HTML comments. + +### 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`{{copy}}: An introduction to the tutorial. + +- `step1.md`{{copy}}: The first step in the tutorial. + +- `finish.md`{{copy}}: A closing page that summarizes steps taken and includes next steps. + +You can also add additional steps using the `step.md`{{copy}}, where _``{{copy}}_ is in the range 2-20. +Steps must be sequential, you can’t have `step1.md`{{copy}} and `step3.md`{{copy}} without a `step2.md`{{copy}}. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +### Exec + +Exec directives tell the transform tool to make the contained fenced code block executable. + +> [!NOTE] +> +> By default, the tool makes `bash`{{copy}} fenced code blocks executable so you don’t need ``{{copy}} directives for bash code blocks. +> You can override this behavior with the ``{{copy}} directives which take precedence over the default behavior. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +### Copy + +Copy directives tell the transform tool to make the contained fenced code block copyable. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{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: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +## Examples + +The best place to see how the meta syntax works is to look at the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. diff --git a/sandbox-developer/sandbox-transformer-walk-through/step4.md b/sandbox-developer/sandbox-transformer-walk-through/step4.md new file mode 100644 index 0000000..3a9d38a --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/step4.md @@ -0,0 +1,57 @@ +# Use the Sandbox Transformer to create a course + +Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn a Markdown docs into a course. Lets use one of the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository: + +1. Navigate back to the root of the `killercoda`{{copy}} repository: + + ```bash + cd ../.. + ```{{exec}} + +1. Make a new directory for your new courses: + + ```bash + mkdir new-courses + ```{{exec}} + + This is where your courses for a specific topic will live. You can create multiple courses in this directory. + +1. Create a new directory for your course: + + ```bash + mkdir new-courses/new-course-1 + ```{{exec}} + +1. We will also create a `structure.json`{{copy}} file more on this later: + + ```bash + touch new-courses/structure.json + ```{{exec}} + +1. Its time to run the transformer on the example course: + + ```bash + ./tools/transformer/transformer docs/examples/complete-docs-example.md new-courses/new-course-1 + ```{{exec}} + + This will transform the `complete-docs-example.md`{{copy}} file into a course in the `new-course-1`{{copy}} directory. + +1. Verify the course was created: + + ```bash + ls new-courses/new-course-1 + ```{{exec}} + + You should see a number of files and directories created for the course. + +1. Finally, add the course to the `structure.json`{{copy}} file: + + ```json + { + "items": [ + { "path": "new-course-1", "title": "New Course 1" } + ] + } + ```{{copy}} + + This will tell Killercoda where to find the course. diff --git a/sandbox-developer/sandbox-transformer-walk-through/step5.md b/sandbox-developer/sandbox-transformer-walk-through/step5.md new file mode 100644 index 0000000..acec705 --- /dev/null +++ b/sandbox-developer/sandbox-transformer-walk-through/step5.md @@ -0,0 +1,34 @@ +# Testing the course + +Before you open a PR to the `killercoda`{{copy}} repository, you should test the course to make sure it works as expected. The easiest way to do this is to run the course via your own Killercoda instance. To do this follow these steps: + +1. Fork the `killercoda`{{copy}} repository to your own GitHub account. This will provide you with a URL to your forked repository. + + ``` + https://github.com//killercoda.git + ```{{copy}} + +1. Add the forked repository as a remote to your local repository: + + ```bash + git remote add forked https://github.com//killercoda.git + ```{{exec}} + +1. Add the changes to your forked repository: + + ```bash + git add . + git commit -m "Add new course" + ```{{exec}} + +1. Push the changes to your forked repository: + +```bash + git push forked my-new-course +```{{exec}} + +1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) + +1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repositor) and add your forked repository. + +1. Once saved, you should see your course in the list of courses. Click on the course to open it. diff --git a/sandbox-developer/structure.json b/sandbox-developer/structure.json new file mode 100644 index 0000000..7b31804 --- /dev/null +++ b/sandbox-developer/structure.json @@ -0,0 +1,5 @@ +{ + "items": [ + { "path": "sandbox-transformer-walk-through", "title": "Learn how to use the Sandbox Transformer"} + ] +} \ No newline at end of file From f51804306063370fa6f1a1987070db1fd4f2aad9 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Fri, 10 Jan 2025 14:11:26 +0000 Subject: [PATCH 02/25] fixed order --- .../sandbox-transformer-walk-through.md | 30 +++++++++---------- .../preprocessed.md | 30 +++++++++---------- .../sandbox-transformer-walk-through/step1.md | 30 +++++++++---------- 3 files changed, 45 insertions(+), 45 deletions(-) diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md index 9fdedd8..3f29948 100644 --- a/docs/examples/sandbox-transformer-walk-through.md +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -32,20 +32,6 @@ The Sandbox Transformer is an experimental tool created by Grafana Labs to turn In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. -## Clone the repository - -First, you need to clone the repository to your local machine. You can do this by running the following command: - -```bash -git clone https://github.com/grafana/killercoda.git -``` - -Its best practise to create a new branch for each new course you create. You can do this by running the following command: - -```bash -git checkout -b my-new-course -``` - ## Install Go The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: @@ -53,7 +39,7 @@ The Sandbox Transformer is written in Go, so you will need to have Go installed 1. Download the Go package: ```bash - wget https://go.dev/dl/go1.23.4.linux-386.tar.gz + wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz ``` 1. Remove old versions of Go and Install the package: @@ -72,6 +58,20 @@ The Sandbox Transformer is written in Go, so you will need to have Go installed go version ``` +## Clone the repository + +First, you need to clone the repository to your local machine. You can do this by running the following command: + +```bash +git clone https://github.com/grafana/killercoda.git && cd killercoda +``` + +Its best practise to create a new branch for each new course you create. You can do this by running the following command: + +```bash +git checkout -b my-new-course +``` + diff --git a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md index 9fdedd8..3f29948 100755 --- a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md +++ b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md @@ -32,20 +32,6 @@ The Sandbox Transformer is an experimental tool created by Grafana Labs to turn In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. -## Clone the repository - -First, you need to clone the repository to your local machine. You can do this by running the following command: - -```bash -git clone https://github.com/grafana/killercoda.git -``` - -Its best practise to create a new branch for each new course you create. You can do this by running the following command: - -```bash -git checkout -b my-new-course -``` - ## Install Go The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: @@ -53,7 +39,7 @@ The Sandbox Transformer is written in Go, so you will need to have Go installed 1. Download the Go package: ```bash - wget https://go.dev/dl/go1.23.4.linux-386.tar.gz + wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz ``` 1. Remove old versions of Go and Install the package: @@ -72,6 +58,20 @@ The Sandbox Transformer is written in Go, so you will need to have Go installed go version ``` +## Clone the repository + +First, you need to clone the repository to your local machine. You can do this by running the following command: + +```bash +git clone https://github.com/grafana/killercoda.git && cd killercoda +``` + +Its best practise to create a new branch for each new course you create. You can do this by running the following command: + +```bash +git checkout -b my-new-course +``` + diff --git a/sandbox-developer/sandbox-transformer-walk-through/step1.md b/sandbox-developer/sandbox-transformer-walk-through/step1.md index 53df475..07ed453 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step1.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step1.md @@ -2,20 +2,6 @@ In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. -## Clone the repository - -First, you need to clone the repository to your local machine. You can do this by running the following command: - -```bash -git clone https://github.com/grafana/killercoda.git -```{{exec}} - -Its best practise to create a new branch for each new course you create. You can do this by running the following command: - -```bash -git checkout -b my-new-course -```{{exec}} - ## Install Go The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: @@ -23,7 +9,7 @@ The Sandbox Transformer is written in Go, so you will need to have Go installed 1. Download the Go package: ```bash - wget https://go.dev/dl/go1.23.4.linux-386.tar.gz + wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz ```{{exec}} 1. Remove old versions of Go and Install the package: @@ -43,3 +29,17 @@ The Sandbox Transformer is written in Go, so you will need to have Go installed ```bash go version ```{{exec}} + +## Clone the repository + +First, you need to clone the repository to your local machine. You can do this by running the following command: + +```bash +git clone https://github.com/grafana/killercoda.git && cd killercoda +```{{exec}} + +Its best practise to create a new branch for each new course you create. You can do this by running the following command: + +```bash +git checkout -b my-new-course +```{{exec}} From fe256e86823fb291e1d51f5c844e181ab3cfa104 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Fri, 10 Jan 2025 14:21:03 +0000 Subject: [PATCH 03/25] fixed identation --- docs/examples/sandbox-transformer-walk-through.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md index 3f29948..7155701 100644 --- a/docs/examples/sandbox-transformer-walk-through.md +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -293,10 +293,11 @@ Before you open a PR to the `killercoda` repository, you should test the course ``` 1. Add the forked repository as a remote to your local repository: - + ```bash git remote add forked https://github.com//killercoda.git ``` + 1. Add the changes to your forked repository: @@ -307,9 +308,9 @@ Before you open a PR to the `killercoda` repository, you should test the course 1. Push the changes to your forked repository: - ```bash + ```bash git push forked my-new-course - ``` + ``` 1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) From f3dc4409db00707585bfcd75a8c2cc9d7525e44f Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Fri, 10 Jan 2025 14:24:59 +0000 Subject: [PATCH 04/25] fixed identation --- .../sandbox-transformer-walk-through/preprocessed.md | 7 ++++--- .../sandbox-transformer-walk-through/step5.md | 8 ++++---- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md index 3f29948..7155701 100755 --- a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md +++ b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md @@ -293,10 +293,11 @@ Before you open a PR to the `killercoda` repository, you should test the course ``` 1. Add the forked repository as a remote to your local repository: - + ```bash git remote add forked https://github.com//killercoda.git ``` + 1. Add the changes to your forked repository: @@ -307,9 +308,9 @@ Before you open a PR to the `killercoda` repository, you should test the course 1. Push the changes to your forked repository: - ```bash + ```bash git push forked my-new-course - ``` + ``` 1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) diff --git a/sandbox-developer/sandbox-transformer-walk-through/step5.md b/sandbox-developer/sandbox-transformer-walk-through/step5.md index acec705..65b54f5 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step5.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step5.md @@ -12,7 +12,7 @@ Before you open a PR to the `killercoda`{{copy}} repository, you should test the ```bash git remote add forked https://github.com//killercoda.git - ```{{exec}} + ```{{copy}} 1. Add the changes to your forked repository: @@ -23,9 +23,9 @@ Before you open a PR to the `killercoda`{{copy}} repository, you should test the 1. Push the changes to your forked repository: -```bash - git push forked my-new-course -```{{exec}} + ```bash + git push forked my-new-course + ```{{exec}} 1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) From 8a4b9b29c0cfe46d15ac8e1b3c21830061716810 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Fri, 10 Jan 2025 15:06:44 +0000 Subject: [PATCH 05/25] added table --- docs/examples/sandbox-transformer-walk-through.md | 15 ++++++++++++++- .../preprocessed.md | 15 ++++++++++++++- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md index 7155701..cc1cc0d 100644 --- a/docs/examples/sandbox-transformer-walk-through.md +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -113,7 +113,20 @@ Here is a breakdown of the basic meta syntax. For more information on the meta s ## 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. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) +The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) + + + +| 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](#finish) 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](#intro) 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](#substitutions). | +| `killercoda.title` | String | The title for the tutorial on the Killercoda website. | + + The following YAML demonstrates a number of the fields: diff --git a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md index 7155701..cc1cc0d 100755 --- a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md +++ b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md @@ -113,7 +113,20 @@ Here is a breakdown of the basic meta syntax. For more information on the meta s ## 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. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) +The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) + + + +| 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](#finish) 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](#intro) 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](#substitutions). | +| `killercoda.title` | String | The title for the tutorial on the Killercoda website. | + + The following YAML demonstrates a number of the fields: From 831eddce3f27d2221e632087eac93d573d30f01d Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 15:20:10 +0000 Subject: [PATCH 06/25] Fix typos and revise note --- sandbox-developer/sandbox-transformer-walk-through/intro.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/sandbox-developer/sandbox-transformer-walk-through/intro.md b/sandbox-developer/sandbox-transformer-walk-through/intro.md index 5913c6c..9b26148 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/intro.md +++ b/sandbox-developer/sandbox-transformer-walk-through/intro.md @@ -1,8 +1,9 @@ # Learn how to use the Sandbox Transformer -The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into KillerCoda courses. This tool is still in development, but we`re excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. +The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into Killercoda courses. This tool is still in development, but we're excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. -> This tutorial will also work with basic Markdown files, however, there are certain Hugo specific features such as the document metadata which is required for the transformer to work. This my interfere with the rendering of the original Markdown file. +> **Note:** This tutorial can also work with non-Hugo Markdown files but it requires that each file has certain [Hugo front matter metadata](https://gohugo.io/content-management/front-matter/). +> This front matter may interfere with the rendering of the original Markdown file. ## What you will learn From 699186bf0bc0dee37c8b3e2e15f40e22dff9b5b6 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Fri, 10 Jan 2025 15:24:38 +0000 Subject: [PATCH 07/25] added nano --- docs/examples/sandbox-transformer-walk-through.md | 6 +++++- .../sandbox-transformer-walk-through/preprocessed.md | 6 +++++- sandbox-developer/sandbox-transformer-walk-through/step4.md | 6 +++++- 3 files changed, 15 insertions(+), 3 deletions(-) diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md index cc1cc0d..ff8dd84 100644 --- a/docs/examples/sandbox-transformer-walk-through.md +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -288,7 +288,11 @@ Now that you have the transformer built and you understand the basic meta syntax ] } ``` - This will tell Killercoda where to find the course. + This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: + + ```bash + nano new-courses/structure.json + ``` diff --git a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md index cc1cc0d..ff8dd84 100755 --- a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md +++ b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md @@ -288,7 +288,11 @@ Now that you have the transformer built and you understand the basic meta syntax ] } ``` - This will tell Killercoda where to find the course. + This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: + + ```bash + nano new-courses/structure.json + ``` diff --git a/sandbox-developer/sandbox-transformer-walk-through/step4.md b/sandbox-developer/sandbox-transformer-walk-through/step4.md index 3a9d38a..150d33f 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step4.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step4.md @@ -54,4 +54,8 @@ Now that you have the transformer built and you understand the basic meta syntax } ```{{copy}} - This will tell Killercoda where to find the course. + This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: + + ```bash + nano new-courses/structure.json + ```{{exec}} From 1cb374bd3d74ff6d8d452c2e397e1af031a62e1e Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 15:27:59 +0000 Subject: [PATCH 08/25] Nitpick --- .../sandbox-transformer-walk-through/step1.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sandbox-developer/sandbox-transformer-walk-through/step1.md b/sandbox-developer/sandbox-transformer-walk-through/step1.md index 07ed453..8d369cb 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step1.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step1.md @@ -6,19 +6,19 @@ In this section we will cover the prerequisites you need to have in place in ord The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: -1. Download the Go package: +1. Download the Go archive: ```bash wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz ```{{exec}} -1. Remove old versions of Go and Install the package: +1. Remove old versions of Go and extract the archive: ```bash rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz ```{{exec}} -1. Add the Go binary to your PATH: +1. Add the Go binary install location to your `PATH` environment variable: ```bash export PATH=$PATH:/usr/local/go/bin @@ -38,7 +38,7 @@ First, you need to clone the repository to your local machine. You can do this b git clone https://github.com/grafana/killercoda.git && cd killercoda ```{{exec}} -Its best practise to create a new branch for each new course you create. You can do this by running the following command: +It's best practise to create a new branch for each new course you create. You can do this by running the following command: ```bash git checkout -b my-new-course From 935b71b0f2f3208ba8a8ea5556393ce033b58c20 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 15:29:24 +0000 Subject: [PATCH 09/25] Fix casing --- sandbox-developer/sandbox-transformer-walk-through/step2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sandbox-developer/sandbox-transformer-walk-through/step2.md b/sandbox-developer/sandbox-transformer-walk-through/step2.md index 5e46f17..fb874a5 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step2.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step2.md @@ -6,7 +6,7 @@ Now that you have the repository cloned and Go installed, you can build the Sand To build the transformer: -1. navigate to the `tools/transformer`{{copy}} directory: +1. Navigate to the `tools/transformer`{{copy}} directory: ```bash cd tools/transformer From 83157e12b1a093a4e0e888e42982cfbcb5742a17 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 15:32:04 +0000 Subject: [PATCH 10/25] Fix note styling Killercoda doesn't support the GitHub Flavored Markdown alert note syntax --- sandbox-developer/sandbox-transformer-walk-through/step3.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sandbox-developer/sandbox-transformer-walk-through/step3.md b/sandbox-developer/sandbox-transformer-walk-through/step3.md index 1b053c0..76cbf33 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step3.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step3.md @@ -63,8 +63,7 @@ The end marker is: Exec directives tell the transform tool to make the contained fenced code block executable. -> [!NOTE] -> +> **Note:** > By default, the tool makes `bash`{{copy}} fenced code blocks executable so you don’t need ``{{copy}} directives for bash code blocks. > You can override this behavior with the ``{{copy}} directives which take precedence over the default behavior. From 0b253a39397e2455b595d0257c40e4ee4af76758 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 15:32:47 +0000 Subject: [PATCH 11/25] Fix Markdown spelling --- .../sandbox-transformer-walk-through/step3.md | 115 ++++++++++++++++++ 1 file changed, 115 insertions(+) diff --git a/sandbox-developer/sandbox-transformer-walk-through/step3.md b/sandbox-developer/sandbox-transformer-walk-through/step3.md index 76cbf33..28488a6 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step3.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step3.md @@ -113,4 +113,119 @@ The end marker is: ## Examples +# Learn the basic meta syntax + +The Sandbox Transformer uses a special syntax to define the metadata for the course. This metadata is used to define the structure of the course and the content of each page. + +Here is a breakdown of the basic meta syntax. For more information on the meta syntax, see the [full documentation](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md) + +## Metadata + +You specify Killercoda tutorial metadata in the source file front matter as the value for the `killercoda`{{copy}} field. +The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) + +The following YAML demonstrates a number of the fields: + +```yaml +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 +```{{copy}} + +## Directives + +Directives in the source file modify how the transformer tool generates the tutorial. +You write directives in the source file with HTML comments. + +### 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`{{copy}}: An introduction to the tutorial. + +- `step1.md`{{copy}}: The first step in the tutorial. + +- `finish.md`{{copy}}: A closing page that summarizes steps taken and includes next steps. + +You can also add additional steps using the `step.md`{{copy}}, where _``{{copy}}_ is in the range 2-20. +Steps must be sequential, you can’t have `step1.md`{{copy}} and `step3.md`{{copy}} without a `step2.md`{{copy}}. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +### Exec + +Exec directives tell the transform tool to make the contained fenced code block executable. + +> **Note:** +> By default, the tool makes `bash`{{copy}} fenced code blocks executable so you don’t need ``{{copy}} directives for bash code blocks. +> You can override this behavior with the ``{{copy}} directives which take precedence over the default behavior. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +### Copy + +Copy directives tell the transform tool to make the contained fenced code block copyable. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{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: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +## Examples + The best place to see how the meta syntax works is to look at the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. From 53a1c0d1ac76a467fa9e0c020d80a36be8001d4d Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 15:34:43 +0000 Subject: [PATCH 12/25] Pretty print JSON --- sandbox-developer/sandbox-transformer-walk-through/step4.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sandbox-developer/sandbox-transformer-walk-through/step4.md b/sandbox-developer/sandbox-transformer-walk-through/step4.md index 3a9d38a..8704169 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step4.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step4.md @@ -1,6 +1,6 @@ # Use the Sandbox Transformer to create a course -Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn a Markdown docs into a course. Lets use one of the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository: +Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn Markdown docs into a course. Lets use one of the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository: 1. Navigate back to the root of the `killercoda`{{copy}} repository: @@ -48,9 +48,9 @@ Now that you have the transformer built and you understand the basic meta syntax ```json { - "items": [ + "items": [ { "path": "new-course-1", "title": "New Course 1" } - ] + ] } ```{{copy}} From 1c58911ee451ba5c2062417aa6473dcb17555b45 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 15:37:53 +0000 Subject: [PATCH 13/25] Link fix and add link to fork the repository --- .../sandbox-transformer-walk-through/step5.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sandbox-developer/sandbox-transformer-walk-through/step5.md b/sandbox-developer/sandbox-transformer-walk-through/step5.md index 65b54f5..699124f 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step5.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step5.md @@ -1,8 +1,8 @@ -# Testing the course +# Test the course Before you open a PR to the `killercoda`{{copy}} repository, you should test the course to make sure it works as expected. The easiest way to do this is to run the course via your own Killercoda instance. To do this follow these steps: -1. Fork the `killercoda`{{copy}} repository to your own GitHub account. This will provide you with a URL to your forked repository. +1. [Fork the `killercoda`{{copy}} repository](https://github.com/grafana/killercoda/fork) to your own GitHub account. This will provide you with a URL to your forked repository. ``` https://github.com//killercoda.git @@ -29,6 +29,6 @@ Before you open a PR to the `killercoda`{{copy}} repository, you should test the 1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) -1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repositor) and add your forked repository. +1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repository) and add your forked repository. -1. Once saved, you should see your course in the list of courses. Click on the course to open it. +1. After you save, you should see your course in the list of courses. Click on the course to open it. From 4566a68acb7f14dbc296531079a7f8e68fce9af6 Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 15:49:46 +0000 Subject: [PATCH 14/25] Fix double copy-paste --- .../sandbox-transformer-walk-through/step3.md | 115 ------------------ 1 file changed, 115 deletions(-) diff --git a/sandbox-developer/sandbox-transformer-walk-through/step3.md b/sandbox-developer/sandbox-transformer-walk-through/step3.md index 28488a6..76cbf33 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step3.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step3.md @@ -113,119 +113,4 @@ The end marker is: ## Examples -# Learn the basic meta syntax - -The Sandbox Transformer uses a special syntax to define the metadata for the course. This metadata is used to define the structure of the course and the content of each page. - -Here is a breakdown of the basic meta syntax. For more information on the meta syntax, see the [full documentation](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md) - -## Metadata - -You specify Killercoda tutorial metadata in the source file front matter as the value for the `killercoda`{{copy}} field. -The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) - -The following YAML demonstrates a number of the fields: - -```yaml -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 -```{{copy}} - -## Directives - -Directives in the source file modify how the transformer tool generates the tutorial. -You write directives in the source file with HTML comments. - -### 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`{{copy}}: An introduction to the tutorial. - -- `step1.md`{{copy}}: The first step in the tutorial. - -- `finish.md`{{copy}}: A closing page that summarizes steps taken and includes next steps. - -You can also add additional steps using the `step.md`{{copy}}, where _``{{copy}}_ is in the range 2-20. -Steps must be sequential, you can’t have `step1.md`{{copy}} and `step3.md`{{copy}} without a `step2.md`{{copy}}. - -The start marker is: - -```markdown - -```{{copy}} - -The end marker is: - -```markdown - -```{{copy}} - -### Exec - -Exec directives tell the transform tool to make the contained fenced code block executable. - -> **Note:** -> By default, the tool makes `bash`{{copy}} fenced code blocks executable so you don’t need ``{{copy}} directives for bash code blocks. -> You can override this behavior with the ``{{copy}} directives which take precedence over the default behavior. - -The start marker is: - -```markdown - -```{{copy}} - -The end marker is: - -```markdown - -```{{copy}} - -### Copy - -Copy directives tell the transform tool to make the contained fenced code block copyable. - -The start marker is: - -```markdown - -```{{copy}} - -The end marker is: - -```markdown - -```{{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: - -```markdown - -```{{copy}} - -The end marker is: - -```markdown - -```{{copy}} - -## Examples - The best place to see how the meta syntax works is to look at the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. From 8ec565ca9f94b541b6a0ed9c9ccad98ad1d18b5a Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Fri, 10 Jan 2025 17:10:20 +0000 Subject: [PATCH 15/25] Implement table extension Signed-off-by: Jack Baldry --- tools/transformer/goldmark/extension/table.go | 101 ++++++++++++++++++ tools/transformer/main.go | 17 ++- 2 files changed, 114 insertions(+), 4 deletions(-) create mode 100644 tools/transformer/goldmark/extension/table.go diff --git a/tools/transformer/goldmark/extension/table.go b/tools/transformer/goldmark/extension/table.go new file mode 100644 index 0000000..8f02c6a --- /dev/null +++ b/tools/transformer/goldmark/extension/table.go @@ -0,0 +1,101 @@ +// Package extension implements Goldmark extensions. +package extension + +import ( + "github.com/yuin/goldmark" + gast "github.com/yuin/goldmark/ast" + "github.com/yuin/goldmark/extension" + "github.com/yuin/goldmark/extension/ast" + "github.com/yuin/goldmark/renderer" + "github.com/yuin/goldmark/util" +) + +// TableMarkdownRenderer is a renderer.NodeRenderer implementation that +// renders Table nodes. +type TableMarkdownRenderer struct { + extension.TableConfig +} + +// NewTableMarkdownRenderer returns a new TableMarkdownRenderer. +func NewTableMarkdownRenderer(opts ...extension.TableOption) renderer.NodeRenderer { + r := &TableMarkdownRenderer{ + TableConfig: extension.NewTableConfig(), + } + for _, opt := range opts { + opt.SetTableOption(&r.TableConfig) + } + return r +} + +// RegisterFuncs implements renderer.NodeRenderer.RegisterFuncs. +func (r *TableMarkdownRenderer) RegisterFuncs(reg renderer.NodeRendererFuncRegisterer) { + reg.Register(ast.KindTable, r.renderTable) + reg.Register(ast.KindTableHeader, r.renderTableHeader) + reg.Register(ast.KindTableRow, r.renderTableRow) + reg.Register(ast.KindTableCell, r.renderTableCell) +} + +func (r *TableMarkdownRenderer) renderTable(w util.BufWriter, source []byte, n gast.Node, entering bool) (gast.WalkStatus, error) { + if !entering { + _, _ = w.WriteString("\n") + } + + return gast.WalkContinue, nil +} + +func (r *TableMarkdownRenderer) renderTableHeader(w util.BufWriter, source []byte, n gast.Node, entering bool) (gast.WalkStatus, error) { + if !entering { + _, _ = w.WriteString("\n") + + // Add a separator line after the header row. + _, _ = w.WriteString("|") + for i := 0; i < n.ChildCount(); i++ { + _, _ = w.WriteString(" --- |") + } + _, _ = w.WriteString("\n") + } + + return gast.WalkContinue, nil +} + +func (r *TableMarkdownRenderer) renderTableRow(w util.BufWriter, _ []byte, n gast.Node, entering bool) (gast.WalkStatus, error) { + if !entering { + _, _ = w.WriteString("\n") + } + + return gast.WalkContinue, nil +} + +func (r *TableMarkdownRenderer) renderTableCell(w util.BufWriter, _ []byte, n gast.Node, entering bool) (gast.WalkStatus, error) { + if entering { + _, _ = w.WriteString("| ") + } else if n.NextSibling() != nil { + _, _ = w.WriteString(" ") + } else { + _, _ = w.WriteString(" |") + } + + return gast.WalkContinue, nil +} + +type table struct { + options []extension.TableOption +} + +// Table is an extension that allow you to use GFM tables . +var Table = &table{ + options: []extension.TableOption{}, +} + +// NewTable returns a new extension with given options. +func NewTable(opts ...extension.TableOption) goldmark.Extender { + return &table{ + options: opts, + } +} + +func (e *table) Extend(m goldmark.Markdown) { + m.Renderer().AddOptions(renderer.WithNodeRenderers( + util.Prioritized(NewTableMarkdownRenderer(e.options...), 500), + )) +} diff --git a/tools/transformer/main.go b/tools/transformer/main.go index b7de3fa..e8dcc5f 100644 --- a/tools/transformer/main.go +++ b/tools/transformer/main.go @@ -12,6 +12,7 @@ import ( "path/filepath" "regexp" + "github.com/grafana/killercoda/tools/transformer/goldmark/extension" "github.com/grafana/killercoda/tools/transformer/killercoda" "github.com/yuin/goldmark" "github.com/yuin/goldmark/text" @@ -91,7 +92,9 @@ func transform(srcFilePath, dstDirPath string) error { md := goldmark.New(goldmark.WithExtensions(&KillercodaExtension{ Transformers: DefaultKillercodaTransformers, AdditionalExtenders: []goldmark.Extender{}, - })) + }, + extension.Table, + )) root := md.Parser().Parse(text.NewReader(data)) @@ -127,7 +130,9 @@ func transform(srcFilePath, dstDirPath string) error { AdditionalExtenders: []goldmark.Extender{ &StepTransformer{StartMarker: pageIntroStartMarker, EndMarker: pageIntroEndMarker}, }, - })) + }, + extension.Table, + )) if err := writeFile(md, dstDirPath, "intro.md", data); err != nil { return err @@ -142,7 +147,9 @@ func transform(srcFilePath, dstDirPath string) error { AdditionalExtenders: []goldmark.Extender{ &StepTransformer{StartMarker: pageFinishStartMarker, EndMarker: pageFinishEndMarker}, }, - })) + }, + extension.Table, + )) if err := writeFile(md, dstDirPath, "finish.md", data); err != nil { return err @@ -167,7 +174,9 @@ func transform(srcFilePath, dstDirPath string) error { AdditionalExtenders: []goldmark.Extender{ &StepTransformer{StartMarker: startMarker, EndMarker: endMarker}, }, - })) + }, + extension.Table, + )) if err := writeFile(md, dstDirPath, fmt.Sprintf("step%d.md", i), data); err != nil { errs = errors.Join(errs, err) From 29c8416101c906cc74b0fa5b157694121a465921 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Mon, 13 Jan 2025 15:48:36 +0000 Subject: [PATCH 16/25] added release workflow --- .github/workflows/release.yml | 32 +++++++++++++++++++ .../sandbox-transformer-walk-through.md | 2 +- 2 files changed, 33 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..63b1507 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,32 @@ +name: Build and Release Transformer + +on: + push: + tags: + - 'v*' # Trigger the workflow when a tag matching 'v*' is pushed + workflow_dispatch: # Allows manual triggering + +jobs: + build-and-release: + runs-on: ubuntu-latest + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + - name: Set up Go + uses: actions/setup-go@v4 + with: + go-version: '1.23' # Adjust this based on the version you need + + - name: Build transformer + run: | + cd tools/transformer + go build -o transformer + + - name: Create release + uses: softprops/action-gh-release@v1 + with: + files: tools/transformer/transformer + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md index ff8dd84..031f74c 100644 --- a/docs/examples/sandbox-transformer-walk-through.md +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -60,7 +60,7 @@ The Sandbox Transformer is written in Go, so you will need to have Go installed ## Clone the repository -First, you need to clone the repository to your local machine. You can do this by running the following command: +You will also need to clone the repository to your local machine. You can do this by running the following command: ```bash git clone https://github.com/grafana/killercoda.git && cd killercoda From bdcfd4b13f7bb893ef1fcf985570f06ee0bac65b Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Mon, 13 Jan 2025 16:23:38 +0000 Subject: [PATCH 17/25] fixed build workflow --- .github/workflows/release.yml | 32 ++++++++++++++++--- .../sandbox-transformer-walk-through.md | 30 ++++------------- 2 files changed, 34 insertions(+), 28 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 63b1507..ccfa4b9 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -9,7 +9,10 @@ on: jobs: build-and-release: runs-on: ubuntu-latest - + strategy: + matrix: + os: [linux, darwin, windows] # Target operating systems + arch: [amd64, arm64] # Target architectures steps: - name: Checkout repository uses: actions/checkout@v3 @@ -21,12 +24,31 @@ jobs: - name: Build transformer run: | - cd tools/transformer - go build -o transformer + mkdir -p release + GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} go build -o release/transformer-${{ matrix.os }}-${{ matrix.arch }} tools/transformer + + - name: Archive build + run: | + zip -j release/transformer-${{ matrix.os }}-${{ matrix.arch }}.zip release/transformer-${{ matrix.os }}-${{ matrix.arch }} + + - name: Upload artifact + uses: actions/upload-artifact@v3 + with: + name: transformer-${{ matrix.os }}-${{ matrix.arch }} + path: release/transformer-${{ matrix.os }}-${{ matrix.arch }}.zip + + release: + needs: build-and-release + runs-on: ubuntu-latest + steps: + - name: Download build artifacts + uses: actions/download-artifact@v3 + with: + path: release - - name: Create release + - name: Create GitHub Release uses: softprops/action-gh-release@v1 with: - files: tools/transformer/transformer + files: release/* env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md index 031f74c..a3d3ce1 100644 --- a/docs/examples/sandbox-transformer-walk-through.md +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -14,9 +14,9 @@ killercoda: # Learn how to use the Sandbox Transformer -The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into KillerCoda courses. This tool is still in development, but we`re excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. +The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into Killercoda courses. This tool is still in development, but we're excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. -> This tutorial will also work with basic Markdown files, however, there are certain Hugo specific features such as the document metadata which is required for the transformer to work. This my interfere with the rendering of the original Markdown file. +> **Note:** This tutorial will also work with basic Markdown files, however, there are certain Hugo specific features such as the document metadata which is required for the transformer to work. This my interfere with the rendering of the original Markdown file. ## What you will learn @@ -30,32 +30,16 @@ The Sandbox Transformer is an experimental tool created by Grafana Labs to turn # Prerequisites -In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. +In this section we will cover the prerequisites you need to have in place in order to download and run the Sandbox Transformer. -## Install Go +## Download the transformer -The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: +The Sandbox Transformer is written in Go and is distributed as a binary. You may also build the transformer from source if you prefer. -1. Download the Go package: +1. Download the Transformer binary from the [releases page](https://github.com/grafana/killercoda/releases): ```bash - wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz - ``` -1. Remove old versions of Go and Install the package: - - ```bash - rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz - ``` - -1. Add the Go binary to your PATH: - - ```bash - export PATH=$PATH:/usr/local/go/bin - ``` -1. Verify the installation: - - ```bash - go version + wget https://github.com/grafana/killercoda/releases/download/v0.1.0/transformer ``` ## Clone the repository From 5758f59e27fc017680472a44cb85939794c053e2 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Mon, 13 Jan 2025 16:30:48 +0000 Subject: [PATCH 18/25] fixed release directory --- .github/workflows/release.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index ccfa4b9..8e71435 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -26,6 +26,7 @@ jobs: run: | mkdir -p release GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} go build -o release/transformer-${{ matrix.os }}-${{ matrix.arch }} tools/transformer + working-directory: ./tools/transformer - name: Archive build run: | From 233077db22992118b22948a4c5f7a898750c03df Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Mon, 13 Jan 2025 16:34:33 +0000 Subject: [PATCH 19/25] fixed release location --- .github/workflows/release.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 8e71435..aa53bdc 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -23,11 +23,11 @@ jobs: go-version: '1.23' # Adjust this based on the version you need - name: Build transformer - run: | - mkdir -p release - GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} go build -o release/transformer-${{ matrix.os }}-${{ matrix.arch }} tools/transformer working-directory: ./tools/transformer - + run: | + mkdir -p ../../release + GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} go build -o ../../release/transformer-${{ matrix.os }}-${{ matrix.arch }} + - name: Archive build run: | zip -j release/transformer-${{ matrix.os }}-${{ matrix.arch }}.zip release/transformer-${{ matrix.os }}-${{ matrix.arch }} From e5f5108ed909236b406c3938f238971047f7f0de Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Mon, 13 Jan 2025 16:42:39 +0000 Subject: [PATCH 20/25] removed zip --- .github/workflows/release.yml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index aa53bdc..aff08de 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -28,15 +28,11 @@ jobs: mkdir -p ../../release GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} go build -o ../../release/transformer-${{ matrix.os }}-${{ matrix.arch }} - - name: Archive build - run: | - zip -j release/transformer-${{ matrix.os }}-${{ matrix.arch }}.zip release/transformer-${{ matrix.os }}-${{ matrix.arch }} - - name: Upload artifact uses: actions/upload-artifact@v3 with: name: transformer-${{ matrix.os }}-${{ matrix.arch }} - path: release/transformer-${{ matrix.os }}-${{ matrix.arch }}.zip + path: release/transformer-${{ matrix.os }}-${{ matrix.arch }} release: needs: build-and-release From 6e4c9885018a1ce9d976ce4f4516806d11f4b8c4 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Mon, 13 Jan 2025 16:53:48 +0000 Subject: [PATCH 21/25] fixed nesting folders --- .github/workflows/release.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index aff08de..761fb00 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -42,6 +42,7 @@ jobs: uses: actions/download-artifact@v3 with: path: release + create_artifact_folder: false - name: Create GitHub Release uses: softprops/action-gh-release@v1 From 4257e8d3d1d3870d75d2329bc21e44d2f7ec45d8 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Tue, 14 Jan 2025 10:28:45 +0000 Subject: [PATCH 22/25] updated build version --- .github/workflows/release.yml | 13 ++++++------- 1 file changed, 6 insertions(+), 7 deletions(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 761fb00..576ab18 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -15,10 +15,10 @@ jobs: arch: [amd64, arm64] # Target architectures steps: - name: Checkout repository - uses: actions/checkout@v3 + uses: actions/checkout@v4 - name: Set up Go - uses: actions/setup-go@v4 + uses: actions/setup-go@v5 with: go-version: '1.23' # Adjust this based on the version you need @@ -29,7 +29,7 @@ jobs: GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} go build -o ../../release/transformer-${{ matrix.os }}-${{ matrix.arch }} - name: Upload artifact - uses: actions/upload-artifact@v3 + uses: actions/upload-artifact@v4 with: name: transformer-${{ matrix.os }}-${{ matrix.arch }} path: release/transformer-${{ matrix.os }}-${{ matrix.arch }} @@ -39,14 +39,13 @@ jobs: runs-on: ubuntu-latest steps: - name: Download build artifacts - uses: actions/download-artifact@v3 + uses: actions/download-artifact@v4 with: path: release - create_artifact_folder: false - name: Create GitHub Release - uses: softprops/action-gh-release@v1 + uses: softprops/action-gh-release@v2 with: - files: release/* + files: release/** env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} From a76ccc39a3caa571e604ffd3e3266c691f76946c Mon Sep 17 00:00:00 2001 From: Jack Baldry Date: Tue, 14 Jan 2025 11:58:13 +0000 Subject: [PATCH 23/25] Harden workflows - Pin actions to immutable references - Don't persist Git credentials so they can't be used in later steps - Don't use a cache during release workflows to avoid cache poisoning Signed-off-by: Jack Baldry --- .github/workflows/ci.yml | 5 ++- .github/workflows/regenerate-tutorials.yml | 43 +++++++++++++--------- .github/workflows/release.yml | 19 +++++----- 3 files changed, 38 insertions(+), 29 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cdb57d4..5bd5c40 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -6,10 +6,11 @@ jobs: if: github.repository == 'grafana/killercoda' runs-on: ubuntu-latest steps: - - uses: actions/checkout@v4 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: path: killercoda - - uses: actions/setup-go@v5 + persist-credentials: false + - uses: actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a # v5.2.0 with: go-version-file: killercoda/tools/transformer/go.mod - run: go test ./... diff --git a/.github/workflows/regenerate-tutorials.yml b/.github/workflows/regenerate-tutorials.yml index 2e15f83..cbe5ed8 100644 --- a/.github/workflows/regenerate-tutorials.yml +++ b/.github/workflows/regenerate-tutorials.yml @@ -9,34 +9,41 @@ jobs: runs-on: ubuntu-latest steps: # Check out all the repositories that contain documentation sources from which we generate tutorials. - - uses: actions/checkout@v4 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: - repository: grafana/loki path: loki - - uses: actions/checkout@v4 + persist-credentials: false + repository: grafana/loki + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: - repository: grafana/grafana path: grafana - - uses: actions/checkout@v4 + persist-credentials: false + repository: grafana/grafana + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: - repository: grafana/alloy - path: alloy - - uses: actions/checkout@v4 + path: alloy + persist-credentials: false + repository: grafana/alloy + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: - repository: grafana/tempo - path: tempo - - uses: actions/checkout@v4 + path: tempo + persist-credentials: false + repository: grafana/tempo + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: - repository: grafana/mimir - path: mimir - - uses: actions/checkout@v4 + path: mimir + persist-credentials: false + repository: grafana/mimir + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: - repository: grafana/pyroscope - path: pyroscope - - uses: actions/checkout@v4 + path: pyroscope + persist-credentials: false + repository: grafana/pyroscope + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 with: path: killercoda - - uses: actions/setup-go@v5 + persist-credentials: false + - uses: actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a # v5.2.0 with: go-version-file: killercoda/tools/transformer/go.mod - run: go build ./ diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 576ab18..ed4ff1d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -14,22 +14,23 @@ jobs: os: [linux, darwin, windows] # Target operating systems arch: [amd64, arm64] # Target architectures steps: - - name: Checkout repository - uses: actions/checkout@v4 + - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + with: + persist-credentials: false - - name: Set up Go - uses: actions/setup-go@v5 + - uses: actions/setup-go@3041bf56c941b39c61721a86cd11f3bb1338122a # v5.2.0 with: - go-version: '1.23' # Adjust this based on the version you need + cache: false + go-version-file: killercoda/tools/transformer/go.mod - name: Build transformer working-directory: ./tools/transformer run: | mkdir -p ../../release GOOS=${{ matrix.os }} GOARCH=${{ matrix.arch }} go build -o ../../release/transformer-${{ matrix.os }}-${{ matrix.arch }} - + - name: Upload artifact - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@65c4c4a1ddee5b72f698fdd19549f0f0fb45cf08 # v4.6.0 with: name: transformer-${{ matrix.os }}-${{ matrix.arch }} path: release/transformer-${{ matrix.os }}-${{ matrix.arch }} @@ -39,12 +40,12 @@ jobs: runs-on: ubuntu-latest steps: - name: Download build artifacts - uses: actions/download-artifact@v4 + uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8 with: path: release - name: Create GitHub Release - uses: softprops/action-gh-release@v2 + uses: softprops/action-gh-release@c95fe1489396fe8a9eb87c0abf8aa5b2ef267fda # v2.2.1 with: files: release/** env: From 5fd62f427fe6cdf26658e01421f11e096bf4b9eb Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Tue, 14 Jan 2025 16:36:34 +0000 Subject: [PATCH 24/25] added table back and removed go build instruct --- .../sandbox-transformer-walk-through.md | 73 ++++------ .../index.json | 3 - .../sandbox-transformer-walk-through/intro.md | 2 +- .../preprocessed.md | 93 ++++-------- .../sandbox-transformer-walk-through/step1.md | 30 ++-- .../sandbox-transformer-walk-through/step2.md | 131 +++++++++++++++-- .../sandbox-transformer-walk-through/step3.md | 137 ++++++------------ .../sandbox-transformer-walk-through/step4.md | 61 +++----- 8 files changed, 240 insertions(+), 290 deletions(-) diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md index a3d3ce1..99f39db 100644 --- a/docs/examples/sandbox-transformer-walk-through.md +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -16,7 +16,8 @@ killercoda: The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into Killercoda courses. This tool is still in development, but we're excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. -> **Note:** This tutorial will also work with basic Markdown files, however, there are certain Hugo specific features such as the document metadata which is required for the transformer to work. This my interfere with the rendering of the original Markdown file. +> **Note:** This tutorial can also work with non-Hugo Markdown files but it requires that each file has certain [Hugo front matter metadata](https://gohugo.io/content-management/front-matter/). +> This front matter may interfere with the rendering of the original Markdown file. ## What you will learn @@ -39,9 +40,16 @@ The Sandbox Transformer is written in Go and is distributed as a binary. You may 1. Download the Transformer binary from the [releases page](https://github.com/grafana/killercoda/releases): ```bash - wget https://github.com/grafana/killercoda/releases/download/v0.1.0/transformer + wget https://github.com/grafana/killercoda/releases/download/v0.1.5/transformer-linux-amd64 -O transformer ``` +1. Make the binary executable: + + ```bash + chmod +x transformer + ``` + + ## Clone the repository You will also need to clone the repository to your local machine. You can do this by running the following command: @@ -58,33 +66,8 @@ git checkout -b my-new-course - - -# Build the Sandbox Transformer - -Now that you have the repository cloned and Go installed, you can build the Sandbox Transformer. - -## Build the transformer - -To build the transformer: - -1. navigate to the `tools/transformer` directory: - - ```bash - cd tools/transformer - ``` - -2. Then run the following command: - - ```bash - go build - ``` - -This will create a binary file called `transformer` in the `tools/transformer` directory. - - - + # Learn the basic meta syntax @@ -99,8 +82,6 @@ Here is a breakdown of the basic meta syntax. For more information on the meta s 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. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) - - | Field | Type | Description | | ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `killercoda.backend.imageid` | String | The name of the Killercoda environment's backend image. Supported values include `ubuntu`. | @@ -110,8 +91,6 @@ 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 @@ -164,7 +143,7 @@ The end marker is: Exec directives tell the transform tool to make the contained fenced code block executable. -> [!NOTE] +> **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. @@ -217,13 +196,13 @@ The end marker is: The best place to see how the meta syntax works is to look at the examples in the `docs/examples` directory of the `killercoda` repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. - + - + # Use the Sandbox Transformer to create a course -Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn a Markdown docs into a course. Lets use one of the examples in the `docs/examples` directory of the `killercoda` repository: +Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn Markdown docs into a course. Lets use one of the examples in the `docs/examples` directory of the `killercoda` repository: 1. Navigate back to the root of the `killercoda` repository: @@ -267,9 +246,9 @@ Now that you have the transformer built and you understand the basic meta syntax ```json { - "items": [ - { "path": "new-course-1", "title": "New Course 1" } - ] + "items": [ + { "path": "new-course-1", "title": "New Course 1" } + ] } ``` This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: @@ -279,16 +258,16 @@ Now that you have the transformer built and you understand the basic meta syntax ``` - + - + -# Testing the course +# Test the course Before you open a PR to the `killercoda` repository, you should test the course to make sure it works as expected. The easiest way to do this is to run the course via your own Killercoda instance. To do this follow these steps: -1. Fork the `killercoda` repository to your own GitHub account. This will provide you with a URL to your forked repository. +1. [Fork the `killercoda`{{copy}} repository](https://github.com/grafana/killercoda/fork) to your own GitHub account. This will provide you with a URL to your forked repository. ``` https://github.com//killercoda.git ``` @@ -314,12 +293,12 @@ Before you open a PR to the `killercoda` repository, you should test the course ``` 1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) + +1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repository) and add your forked repository. -1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repositor) and add your forked repository. - -1. Once saved, you should see your course in the list of courses. Click on the course to open it. +1. After you save, you should see your course in the list of courses. Click on the course to open it. - + diff --git a/sandbox-developer/sandbox-transformer-walk-through/index.json b/sandbox-developer/sandbox-transformer-walk-through/index.json index c72a6e3..bf2f564 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/index.json +++ b/sandbox-developer/sandbox-transformer-walk-through/index.json @@ -17,9 +17,6 @@ }, { "text": "step4.md" - }, - { - "text": "step5.md" } ], "finish": { diff --git a/sandbox-developer/sandbox-transformer-walk-through/intro.md b/sandbox-developer/sandbox-transformer-walk-through/intro.md index 9b26148..b9e127a 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/intro.md +++ b/sandbox-developer/sandbox-transformer-walk-through/intro.md @@ -1,6 +1,6 @@ # Learn how to use the Sandbox Transformer -The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into Killercoda courses. This tool is still in development, but we're excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. +The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into Killercoda courses. This tool is still in development, but we’re excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. > **Note:** This tutorial can also work with non-Hugo Markdown files but it requires that each file has certain [Hugo front matter metadata](https://gohugo.io/content-management/front-matter/). > This front matter may interfere with the rendering of the original Markdown file. diff --git a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md index ff8dd84..99f39db 100755 --- a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md +++ b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md @@ -14,9 +14,10 @@ killercoda: # Learn how to use the Sandbox Transformer -The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into KillerCoda courses. This tool is still in development, but we`re excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. +The Sandbox Transformer is an experimental tool created by Grafana Labs to turn **Hugo Markdown** files into Killercoda courses. This tool is still in development, but we're excited to share it with you and get your feedback. In this tutorial, you will learn how to use the Sandbox Transformer to turn Hugo docs into a course. -> This tutorial will also work with basic Markdown files, however, there are certain Hugo specific features such as the document metadata which is required for the transformer to work. This my interfere with the rendering of the original Markdown file. +> **Note:** This tutorial can also work with non-Hugo Markdown files but it requires that each file has certain [Hugo front matter metadata](https://gohugo.io/content-management/front-matter/). +> This front matter may interfere with the rendering of the original Markdown file. ## What you will learn @@ -30,37 +31,28 @@ The Sandbox Transformer is an experimental tool created by Grafana Labs to turn # Prerequisites -In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. +In this section we will cover the prerequisites you need to have in place in order to download and run the Sandbox Transformer. -## Install Go +## Download the transformer -The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: +The Sandbox Transformer is written in Go and is distributed as a binary. You may also build the transformer from source if you prefer. -1. Download the Go package: +1. Download the Transformer binary from the [releases page](https://github.com/grafana/killercoda/releases): ```bash - wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz - ``` -1. Remove old versions of Go and Install the package: - - ```bash - rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz + wget https://github.com/grafana/killercoda/releases/download/v0.1.5/transformer-linux-amd64 -O transformer ``` -1. Add the Go binary to your PATH: - +1. Make the binary executable: + ```bash - export PATH=$PATH:/usr/local/go/bin + chmod +x transformer ``` -1. Verify the installation: - ```bash - go version - ``` ## Clone the repository -First, you need to clone the repository to your local machine. You can do this by running the following command: +You will also need to clone the repository to your local machine. You can do this by running the following command: ```bash git clone https://github.com/grafana/killercoda.git && cd killercoda @@ -74,33 +66,8 @@ git checkout -b my-new-course - - -# Build the Sandbox Transformer - -Now that you have the repository cloned and Go installed, you can build the Sandbox Transformer. - -## Build the transformer - -To build the transformer: - -1. navigate to the `tools/transformer` directory: - - ```bash - cd tools/transformer - ``` - -2. Then run the following command: - - ```bash - go build - ``` -This will create a binary file called `transformer` in the `tools/transformer` directory. - - - - + # Learn the basic meta syntax @@ -115,8 +82,6 @@ Here is a breakdown of the basic meta syntax. For more information on the meta s 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. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) - - | Field | Type | Description | | ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `killercoda.backend.imageid` | String | The name of the Killercoda environment's backend image. Supported values include `ubuntu`. | @@ -126,8 +91,6 @@ 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 @@ -180,7 +143,7 @@ The end marker is: Exec directives tell the transform tool to make the contained fenced code block executable. -> [!NOTE] +> **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. @@ -233,13 +196,13 @@ The end marker is: The best place to see how the meta syntax works is to look at the examples in the `docs/examples` directory of the `killercoda` repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. - + - + # Use the Sandbox Transformer to create a course -Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn a Markdown docs into a course. Lets use one of the examples in the `docs/examples` directory of the `killercoda` repository: +Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn Markdown docs into a course. Lets use one of the examples in the `docs/examples` directory of the `killercoda` repository: 1. Navigate back to the root of the `killercoda` repository: @@ -283,9 +246,9 @@ Now that you have the transformer built and you understand the basic meta syntax ```json { - "items": [ - { "path": "new-course-1", "title": "New Course 1" } - ] + "items": [ + { "path": "new-course-1", "title": "New Course 1" } + ] } ``` This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: @@ -295,16 +258,16 @@ Now that you have the transformer built and you understand the basic meta syntax ``` - + - + -# Testing the course +# Test the course Before you open a PR to the `killercoda` repository, you should test the course to make sure it works as expected. The easiest way to do this is to run the course via your own Killercoda instance. To do this follow these steps: -1. Fork the `killercoda` repository to your own GitHub account. This will provide you with a URL to your forked repository. +1. [Fork the `killercoda`{{copy}} repository](https://github.com/grafana/killercoda/fork) to your own GitHub account. This will provide you with a URL to your forked repository. ``` https://github.com//killercoda.git ``` @@ -330,12 +293,12 @@ Before you open a PR to the `killercoda` repository, you should test the course ``` 1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) + +1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repository) and add your forked repository. -1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repositor) and add your forked repository. - -1. Once saved, you should see your course in the list of courses. Click on the course to open it. +1. After you save, you should see your course in the list of courses. Click on the course to open it. - + diff --git a/sandbox-developer/sandbox-transformer-walk-through/step1.md b/sandbox-developer/sandbox-transformer-walk-through/step1.md index 8d369cb..016e53a 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step1.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step1.md @@ -1,44 +1,32 @@ # Prerequisites -In this section we will cover the prerequisites you need to have in place in order to build and run the Sandbox Transformer. +In this section we will cover the prerequisites you need to have in place in order to download and run the Sandbox Transformer. -## Install Go +## Download the transformer -The Sandbox Transformer is written in Go, so you will need to have Go installed on your machine. You can download Go from the official website [here](https://golang.org/dl/). In this case we will install the Ubuntu package: +The Sandbox Transformer is written in Go and is distributed as a binary. You may also build the transformer from source if you prefer. -1. Download the Go archive: +1. Download the Transformer binary from the [releases page](https://github.com/grafana/killercoda/releases): ```bash - wget https://go.dev/dl/go1.23.4.linux-amd64.tar.gz + wget https://github.com/grafana/killercoda/releases/download/v0.1.5/transformer-linux-amd64 -O transformer ```{{exec}} -1. Remove old versions of Go and extract the archive: +1. Make the binary executable: ```bash - rm -rf /usr/local/go && tar -C /usr/local -xzf go1.23.4.linux-amd64.tar.gz - ```{{exec}} - -1. Add the Go binary install location to your `PATH` environment variable: - - ```bash - export PATH=$PATH:/usr/local/go/bin - ```{{exec}} - -1. Verify the installation: - - ```bash - go version + chmod +x transformer ```{{exec}} ## Clone the repository -First, you need to clone the repository to your local machine. You can do this by running the following command: +You will also need to clone the repository to your local machine. You can do this by running the following command: ```bash git clone https://github.com/grafana/killercoda.git && cd killercoda ```{{exec}} -It's best practise to create a new branch for each new course you create. You can do this by running the following command: +Its best practise to create a new branch for each new course you create. You can do this by running the following command: ```bash git checkout -b my-new-course diff --git a/sandbox-developer/sandbox-transformer-walk-through/step2.md b/sandbox-developer/sandbox-transformer-walk-through/step2.md index fb874a5..b724848 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step2.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step2.md @@ -1,21 +1,126 @@ -# Build the Sandbox Transformer +# Learn the basic meta syntax -Now that you have the repository cloned and Go installed, you can build the Sandbox Transformer. +The Sandbox Transformer uses a special syntax to define the metadata for the course. This metadata is used to define the structure of the course and the content of each page. -## Build the transformer +Here is a breakdown of the basic meta syntax. For more information on the meta syntax, see the [full documentation](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md) -To build the transformer: +## Metadata -1. Navigate to the `tools/transformer`{{copy}} directory: +You specify Killercoda tutorial metadata in the source file front matter as the value for the `killercoda`{{copy}} field. +The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) - ```bash - cd tools/transformer - ```{{exec}} +| Field | Type | Description | +| --- | --- | --- | +| `killercoda.backend.imageid`{{copy}} | String | The name of the Killercoda environment’s backend image. Supported values include `ubuntu`{{copy}}. | +| `killercoda.description`{{copy}} | String | The description displayed on the Killercoda website | +| `killercoda.details.finish.text`{{copy}} | String | The filename of the finish page Markdown source in the `grafana/killercoda`{{copy}} repository. A [finish directive](https://grafana.com#finish) in the documentation source overrides this. | +| `killercoda.details.intro.text`{{copy}} | String | The filename of the introduction page Markdown source in the `grafana/killercoda`{{copy}} repository. An [intro directive](https://grafana.com#intro) in the documentation source overrides this. | +| `killercoda.preprocessing.substitutions`{{copy}} | Array | Substitute matches of a regular expression with a replacement. For more information, refer to [Substitutions](https://grafana.com#substitutions). | +| `killercoda.title`{{copy}} | String | The title for the tutorial on the Killercoda website. | -1. Then run the following command: +The following YAML demonstrates a number of the fields: - ```bash - go build - ```{{exec}} +```yaml +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 +```{{copy}} -This will create a binary file called `transformer`{{copy}} in the `tools/transformer`{{copy}} directory. +## Directives + +Directives in the source file modify how the transformer tool generates the tutorial. +You write directives in the source file with HTML comments. + +### 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`{{copy}}: An introduction to the tutorial. + +- `step1.md`{{copy}}: The first step in the tutorial. + +- `finish.md`{{copy}}: A closing page that summarizes steps taken and includes next steps. + +You can also add additional steps using the `step.md`{{copy}}, where _``{{copy}}_ is in the range 2-20. +Steps must be sequential, you can’t have `step1.md`{{copy}} and `step3.md`{{copy}} without a `step2.md`{{copy}}. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +### Exec + +Exec directives tell the transform tool to make the contained fenced code block executable. + +> **Note:** +> +> By default, the tool makes `bash`{{copy}} fenced code blocks executable so you don’t need ``{{copy}} directives for bash code blocks. +> You can override this behavior with the ``{{copy}} directives which take precedence over the default behavior. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +### Copy + +Copy directives tell the transform tool to make the contained fenced code block copyable. + +The start marker is: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{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: + +```markdown + +```{{copy}} + +The end marker is: + +```markdown + +```{{copy}} + +## Examples + +The best place to see how the meta syntax works is to look at the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. diff --git a/sandbox-developer/sandbox-transformer-walk-through/step3.md b/sandbox-developer/sandbox-transformer-walk-through/step3.md index 76cbf33..feb0dc8 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step3.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step3.md @@ -1,116 +1,61 @@ -# Learn the basic meta syntax +# Use the Sandbox Transformer to create a course -The Sandbox Transformer uses a special syntax to define the metadata for the course. This metadata is used to define the structure of the course and the content of each page. +Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn Markdown docs into a course. Lets use one of the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository: -Here is a breakdown of the basic meta syntax. For more information on the meta syntax, see the [full documentation](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md) +1. Navigate back to the root of the `killercoda`{{copy}} repository: -## Metadata + ```bash + cd ../.. + ```{{exec}} -You specify Killercoda tutorial metadata in the source file front matter as the value for the `killercoda`{{copy}} field. -The tool uses the metadata to perform preprocessing on the source file and generate the Killercoda configuration files for the tutorial. A table of the metadata fields can be found [here](https://github.com/grafana/killercoda/blob/staging/docs/transformer.md#metadata) +1. Make a new directory for your new courses: -The following YAML demonstrates a number of the fields: + ```bash + mkdir new-courses + ```{{exec}} -```yaml -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 -```{{copy}} + This is where your courses for a specific topic will live. You can create multiple courses in this directory. -## Directives +1. Create a new directory for your course: -Directives in the source file modify how the transformer tool generates the tutorial. -You write directives in the source file with HTML comments. + ```bash + mkdir new-courses/new-course-1 + ```{{exec}} -### Page +1. We will also create a `structure.json`{{copy}} file more on this later: -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. + ```bash + touch new-courses/structure.json + ```{{exec}} -Every tutorial must have at least the pages: +1. Its time to run the transformer on the example course: -- `intro.md`{{copy}}: An introduction to the tutorial. + ```bash + ./tools/transformer/transformer docs/examples/complete-docs-example.md new-courses/new-course-1 + ```{{exec}} -- `step1.md`{{copy}}: The first step in the tutorial. + This will transform the `complete-docs-example.md`{{copy}} file into a course in the `new-course-1`{{copy}} directory. -- `finish.md`{{copy}}: A closing page that summarizes steps taken and includes next steps. +1. Verify the course was created: -You can also add additional steps using the `step.md`{{copy}}, where _``{{copy}}_ is in the range 2-20. -Steps must be sequential, you can’t have `step1.md`{{copy}} and `step3.md`{{copy}} without a `step2.md`{{copy}}. + ```bash + ls new-courses/new-course-1 + ```{{exec}} -The start marker is: + You should see a number of files and directories created for the course. -```markdown - -```{{copy}} +1. Finally, add the course to the `structure.json`{{copy}} file: -The end marker is: + ```json + { + "items": [ + { "path": "new-course-1", "title": "New Course 1" } + ] + } + ```{{copy}} -```markdown - -```{{copy}} + This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: -### Exec - -Exec directives tell the transform tool to make the contained fenced code block executable. - -> **Note:** -> By default, the tool makes `bash`{{copy}} fenced code blocks executable so you don’t need ``{{copy}} directives for bash code blocks. -> You can override this behavior with the ``{{copy}} directives which take precedence over the default behavior. - -The start marker is: - -```markdown - -```{{copy}} - -The end marker is: - -```markdown - -```{{copy}} - -### Copy - -Copy directives tell the transform tool to make the contained fenced code block copyable. - -The start marker is: - -```markdown - -```{{copy}} - -The end marker is: - -```markdown - -```{{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: - -```markdown - -```{{copy}} - -The end marker is: - -```markdown - -```{{copy}} - -## Examples - -The best place to see how the meta syntax works is to look at the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository. You can find examples of how to structure your markdown files and how to use the meta syntax to define the structure of your course. + ```bash + nano new-courses/structure.json + ```{{exec}} diff --git a/sandbox-developer/sandbox-transformer-walk-through/step4.md b/sandbox-developer/sandbox-transformer-walk-through/step4.md index 191e468..f9f405d 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step4.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step4.md @@ -1,61 +1,34 @@ -# Use the Sandbox Transformer to create a course +# Test the course -Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn Markdown docs into a course. Lets use one of the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository: +Before you open a PR to the `killercoda`{{copy}} repository, you should test the course to make sure it works as expected. The easiest way to do this is to run the course via your own Killercoda instance. To do this follow these steps: -1. Navigate back to the root of the `killercoda`{{copy}} repository: +1. [Fork the `killercoda`{{copy}}{{copy}} repository](https://github.com/grafana/killercoda/fork) to your own GitHub account. This will provide you with a URL to your forked repository. - ```bash - cd ../.. - ```{{exec}} - -1. Make a new directory for your new courses: - - ```bash - mkdir new-courses - ```{{exec}} - - This is where your courses for a specific topic will live. You can create multiple courses in this directory. - -1. Create a new directory for your course: - - ```bash - mkdir new-courses/new-course-1 - ```{{exec}} + ``` + https://github.com//killercoda.git + ```{{copy}} -1. We will also create a `structure.json`{{copy}} file more on this later: +1. Add the forked repository as a remote to your local repository: ```bash - touch new-courses/structure.json - ```{{exec}} + git remote add forked https://github.com//killercoda.git + ```{{copy}} -1. Its time to run the transformer on the example course: +1. Add the changes to your forked repository: ```bash - ./tools/transformer/transformer docs/examples/complete-docs-example.md new-courses/new-course-1 + git add . + git commit -m "Add new course" ```{{exec}} - This will transform the `complete-docs-example.md`{{copy}} file into a course in the `new-course-1`{{copy}} directory. - -1. Verify the course was created: +1. Push the changes to your forked repository: ```bash - ls new-courses/new-course-1 + git push forked my-new-course ```{{exec}} - You should see a number of files and directories created for the course. +1. Create a Killercoda account: [https://killercoda.com/login](https://killercoda.com/login) -1. Finally, add the course to the `structure.json`{{copy}} file: +1. Then head to: [https://killercoda.com/creator/repository](https://killercoda.com/creator/repository) and add your forked repository. - ```json - { - "items": [ - { "path": "new-course-1", "title": "New Course 1" } - ] - } - ```{{copy}} - - This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: - - ```bash - nano new-courses/structure.json - ```{{exec}} +1. After you save, you should see your course in the list of courses. Click on the course to open it. From 235dc6ca0dc112b075768fed714f8727600f0279 Mon Sep 17 00:00:00 2001 From: Jayclifford345 Date: Tue, 14 Jan 2025 16:41:40 +0000 Subject: [PATCH 25/25] fixed pathing --- .../sandbox-transformer-walk-through.md | 22 ++++++++++++------- .../preprocessed.md | 22 ++++++++++++------- .../sandbox-transformer-walk-through/step3.md | 16 +++++++------- .../sandbox-transformer-walk-through/step4.md | 6 +++++ 4 files changed, 42 insertions(+), 24 deletions(-) diff --git a/docs/examples/sandbox-transformer-walk-through.md b/docs/examples/sandbox-transformer-walk-through.md index 99f39db..6fdf5c5 100644 --- a/docs/examples/sandbox-transformer-walk-through.md +++ b/docs/examples/sandbox-transformer-walk-through.md @@ -204,41 +204,41 @@ The best place to see how the meta syntax works is to look at the examples in th Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn Markdown docs into a course. Lets use one of the examples in the `docs/examples` directory of the `killercoda` repository: -1. Navigate back to the root of the `killercoda` repository: +1. Navigate out of the `killercoda` repository: ```bash - cd ../.. + cd ../ ``` 1. Make a new directory for your new courses: ```bash - mkdir new-courses + mkdir killercoda/new-courses ``` This is where your courses for a specific topic will live. You can create multiple courses in this directory. 1. Create a new directory for your course: ```bash - mkdir new-courses/new-course-1 + mkdir killercoda/new-courses/new-course-1 ``` 1. We will also create a `structure.json` file more on this later: ```bash - touch new-courses/structure.json + touch killercoda/new-courses/structure.json ``` 1. Its time to run the transformer on the example course: ```bash - ./tools/transformer/transformer docs/examples/complete-docs-example.md new-courses/new-course-1 + ./transformer killercoda/docs/examples/complete-docs-example.md killercoda/new-courses/new-course-1 ``` This will transform the `complete-docs-example.md` file into a course in the `new-course-1` directory. 1. Verify the course was created: ```bash - ls new-courses/new-course-1 + ls killercoda/new-courses/new-course-1 ``` You should see a number of files and directories created for the course. @@ -254,7 +254,7 @@ Now that you have the transformer built and you understand the basic meta syntax This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: ```bash - nano new-courses/structure.json + nano killercoda/new-courses/structure.json ``` @@ -271,6 +271,12 @@ Before you open a PR to the `killercoda` repository, you should test the course ``` https://github.com//killercoda.git ``` + +1. change back to the `killercoda` repository: + + ```bash + cd killercoda + ``` 1. Add the forked repository as a remote to your local repository: diff --git a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md index 99f39db..6fdf5c5 100755 --- a/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md +++ b/sandbox-developer/sandbox-transformer-walk-through/preprocessed.md @@ -204,41 +204,41 @@ The best place to see how the meta syntax works is to look at the examples in th Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn Markdown docs into a course. Lets use one of the examples in the `docs/examples` directory of the `killercoda` repository: -1. Navigate back to the root of the `killercoda` repository: +1. Navigate out of the `killercoda` repository: ```bash - cd ../.. + cd ../ ``` 1. Make a new directory for your new courses: ```bash - mkdir new-courses + mkdir killercoda/new-courses ``` This is where your courses for a specific topic will live. You can create multiple courses in this directory. 1. Create a new directory for your course: ```bash - mkdir new-courses/new-course-1 + mkdir killercoda/new-courses/new-course-1 ``` 1. We will also create a `structure.json` file more on this later: ```bash - touch new-courses/structure.json + touch killercoda/new-courses/structure.json ``` 1. Its time to run the transformer on the example course: ```bash - ./tools/transformer/transformer docs/examples/complete-docs-example.md new-courses/new-course-1 + ./transformer killercoda/docs/examples/complete-docs-example.md killercoda/new-courses/new-course-1 ``` This will transform the `complete-docs-example.md` file into a course in the `new-course-1` directory. 1. Verify the course was created: ```bash - ls new-courses/new-course-1 + ls killercoda/new-courses/new-course-1 ``` You should see a number of files and directories created for the course. @@ -254,7 +254,7 @@ Now that you have the transformer built and you understand the basic meta syntax This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: ```bash - nano new-courses/structure.json + nano killercoda/new-courses/structure.json ``` @@ -271,6 +271,12 @@ Before you open a PR to the `killercoda` repository, you should test the course ``` https://github.com//killercoda.git ``` + +1. change back to the `killercoda` repository: + + ```bash + cd killercoda + ``` 1. Add the forked repository as a remote to your local repository: diff --git a/sandbox-developer/sandbox-transformer-walk-through/step3.md b/sandbox-developer/sandbox-transformer-walk-through/step3.md index feb0dc8..a9b3613 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step3.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step3.md @@ -2,16 +2,16 @@ Now that you have the transformer built and you understand the basic meta syntax, you can use the Sandbox Transformer to turn Markdown docs into a course. Lets use one of the examples in the `docs/examples`{{copy}} directory of the `killercoda`{{copy}} repository: -1. Navigate back to the root of the `killercoda`{{copy}} repository: +1. Navigate out of the `killercoda`{{copy}} repository: ```bash - cd ../.. + cd ../ ```{{exec}} 1. Make a new directory for your new courses: ```bash - mkdir new-courses + mkdir killercoda/new-courses ```{{exec}} This is where your courses for a specific topic will live. You can create multiple courses in this directory. @@ -19,19 +19,19 @@ Now that you have the transformer built and you understand the basic meta syntax 1. Create a new directory for your course: ```bash - mkdir new-courses/new-course-1 + mkdir killercoda/new-courses/new-course-1 ```{{exec}} 1. We will also create a `structure.json`{{copy}} file more on this later: ```bash - touch new-courses/structure.json + touch killercoda/new-courses/structure.json ```{{exec}} 1. Its time to run the transformer on the example course: ```bash - ./tools/transformer/transformer docs/examples/complete-docs-example.md new-courses/new-course-1 + ./transformer killercoda/docs/examples/complete-docs-example.md killercoda/new-courses/new-course-1 ```{{exec}} This will transform the `complete-docs-example.md`{{copy}} file into a course in the `new-course-1`{{copy}} directory. @@ -39,7 +39,7 @@ Now that you have the transformer built and you understand the basic meta syntax 1. Verify the course was created: ```bash - ls new-courses/new-course-1 + ls killercoda/new-courses/new-course-1 ```{{exec}} You should see a number of files and directories created for the course. @@ -57,5 +57,5 @@ Now that you have the transformer built and you understand the basic meta syntax This will tell Killercoda where to find the course. This can be done via the inbuilt code editor in the Killercoda UI. Or you can use nano: ```bash - nano new-courses/structure.json + nano killercoda/new-courses/structure.json ```{{exec}} diff --git a/sandbox-developer/sandbox-transformer-walk-through/step4.md b/sandbox-developer/sandbox-transformer-walk-through/step4.md index f9f405d..f1597f8 100644 --- a/sandbox-developer/sandbox-transformer-walk-through/step4.md +++ b/sandbox-developer/sandbox-transformer-walk-through/step4.md @@ -8,6 +8,12 @@ Before you open a PR to the `killercoda`{{copy}} repository, you should test the https://github.com//killercoda.git ```{{copy}} +1. change back to the `killercoda`{{copy}} repository: + + ```bash + cd killercoda + ```{{exec}} + 1. Add the forked repository as a remote to your local repository: ```bash