Update documentation

Signed-off-by: Jack Baldry <jack.baldry@grafana.com>
grafana · Jun 27, 2024 · da9b1c4 · da9b1c4
1 parent 136e5b7
commit da9b1c4
Showing 1 changed file with 26 additions and 89 deletions.
diff --git a/docs/transformer.md b/docs/transformer.md
@@ -18,7 +18,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
@@ -52,54 +51,11 @@ You write directives in the source file with HTML comments.
 
 Use directives to:
 
-- [Configure copyable code blocks](#copy)
 - [Configure executable code blocks](#exec)
-- [Define an introduction page](#intro)
-- [Define a finish page](#finish)
-- [Define step pages](#step)
+- [Define pages](#page)
 - [Ignore parts of the documentation](#ignore)
 - [Include extra parts not in the website page](#include)
 
-### Copy
-
-Copy directives tell the transform tool to make the contained fenced code block copyable.
-
-The start marker is:
-
-```markdown
-<!-- INTERACTIVE copy START -->
-```
-
-The end marker is:
-
-```markdown
-<!-- INTERACTIVE copy END -->
-```
-
-#### Examples
-
-````markdown
-<!-- INTERACTIVE copy START -->
-
-```bash
-echo 'Hello, world!'
-```
-
-<!-- INTERACTIVE copy END -->
-````
-
-Produces:
-
-<!-- prettier-ignore-start -->
-
-````markdown
-```bash
-echo 'Hello, world!'
-```{{exec}}
-````
-
-<!-- prettier-ignore-end -->
-
 ### Exec
 
 Exec directives tell the transform tool to make the contained fenced code block executable.
@@ -140,23 +96,6 @@ echo 'Hello, world!'
 
 <!-- prettier-ignore-end -->
 
-### Finish
-
-The finish directive specifies the start and end of the section of the file to use as the Killercoda finish page.
-If this is present, it overrides the `killercoda.details.finish.text` front matter.
-
-The start marker is:
-
-```markdown
-<!-- INTERACTIVE finish.md START -->
-```
-
-The end marker is:
-
-```markdown
-<!-- INTERACTIVE finish.md END -->
-```
-
 ### Ignore
 
 The ignore directive tells the transform tool to skip the contents within the markers when generating the Killercoda page.
@@ -226,37 +165,30 @@ Information common to both pages.
 Information unique to the Killercoda page.
 ```
 
-### Intro
+### Page
 
-The intro directive specifies the start and end of the section of the file to use as the Killercoda introduction page.
-If this is present, it overrides the `killercoda.details.intro.text` front matter.
+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.
 
-The start marker is:
-
-```markdown
-<!-- INTERACTIVE intro.md START -->
-```
+Every tutorial must have at least the pages:
 
-The end marker is:
-
-```markdown
-<!-- INTERACTIVE intro.md END -->
-```
+- `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.
 
-### Step
+You can also add additional steps using the `step<N>.md`, where _`<N>`_ is in the range 2-20.
+Steps must be sequential, you can't have `step1.md` and `step3.md` without a `step2.md`.
 
-The step directive specifies the start and end of the section of the file to use as a Killercoda step page.
-
-The start marker is the following, where _`<N>`_ is the number of the step:
+The start marker is:
 
 ```markdown
-<!-- INTERACTIVE step<N>.md START -->
+<!-- INTERACTIVE page <FILENAME> START -->
 ```
 
-The end marker is the following, where _`<N>`_ is the number of the step:
+The end marker is:
 
 ```markdown
-<!-- INTERACTIVE step<N>.md END -->
+<!-- INTERACTIVE page <FILENAME> END -->
 ```
 
 ## Generate a tutorial
@@ -288,27 +220,32 @@ To generate a tutorial:
    Front matter is YAML metadata written before the page's content.
    For more information, refer to the [Hugo front matter documentation](https://gohugo.io/content-management/front-matter/).
 
-   For an example Killercoda front matter, refer to [Metadata](#Metadata)
+   For an example Killercoda front matter, refer to [Metadata](#metadata).
 
 1. Configure an introduction page.
 
    Use one of the two options:
 
-   1. In the source repository, add [intro](#intro) directives.
+   1. In the source repository, add the [page](#page) directives with the `intro.md` argument.
+
+      The start marker is `<!-- INTERACTIVE page intro.md START -->` and the end marker is `<!-- INTERACTIVE page intro.md END -->`.
+
    1. 1. In the Killercoda repository, add a `intro.md` file in the output tutorial directory.
       1. In the source file, add the `killercoda.details.intro.text` field with the value `intro.md`.
 
-1. Add directives for each step in the tutorial.
+1. Add [page](#page) directives for each step in the tutorial.
 
-   Each step starts at the [step](#step) directive start marker and ends at the [step](#step) directive end marker.
-   Include at least one step.
-   The first step use the start marker `<!-- INTERACTIVE step1.md START -->` and the end marker `<!-- INTERACTIVE step1.md END -->`
+   You must include at least one step.
+   The first step uses the start marker `<!-- INTERACTIVE page step1.md START -->` and the end marker `<!-- INTERACTIVE page step1.md END -->`.
 
 1. Configure a finish page.
 
    Use one of the two options:
 
-   1. In the source repository, add [finish](#finish) directives.
+   1. In the source repository, add the [page](#page) directives with the `finish.md` argument.
+
+      The start marker is `<!-- INTERACTIVE page finish.md START -->` and the end marker is `<!-- INTERACTIVE page finish.md END -->`.
+
    1. 1. In the Killercoda repository, add a `finish.md` file in the output tutorial directory.
       1. In the source file, add the `killercoda.details.finish.text` field with the value `finish.md`.