# Authoring Katacoda Scenarios

# Markdown 101

Markdown is at the heart of every Katacoda scenario. Markdown is a lightweight markup language with plain-text-formatting syntax.

The Markdown within Katacoda allows you to apply styling, create lists, include code snippets and more. More can be learned at https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet

Katacoda uses GitHub Flavored Markdown. To learn more visit https://guides.github.com/features/mastering-markdown/

# Katacoda's Markdown Extensions

Katacoda builds on the existing Markdown functionality and has extended in certain cases to incorporate additional UI capabilities.

# UI Shortcuts

Katacoda has introduced UI shortcuts to help the learner focus on the topic instead of copying long commands. These are optional and up-to the author to use as and when they feel appropriate.

# Execute

The action execute will make any code snippet executable within the terminal.

This can be added to any code snippet, such as:

`top`{{execute}}

If you wish the command to be run in a separate terminal tab, include "T#", where #Β is the Tab number. This allows certain tabs to be re-used for certain actions.

# Interrupt

When using execute, include interrupt to execute a Ctrl+C, stopping any previous running task. Useful if the previous commands in the terminal might capture user input, such as top.

This can be added to any code snippet, such as:

`top`{{execute interrupt}}

# Copy

The use of copy will copy the command to the user's clipboard.

This can be added to any code snippet, such as:

`top`{{copy}}

# Open

For use with files, open will automatically open the file in the editor.

This can be added to any code snippet, such as:

`myfile.js`{{open}}

A path may be given to the file, but that path will be relative to the "uieditorpath" setting given in index.json. Only files below that path will be listed in the tree view of files for the editor. The default value for "uieditorpath" is /root.

# Example

Terminal Text Example

Learn more about the extensions at https://katacoda.com/scenario-examples/scenarios/markdown-extensions

# Control Sequences

Learn more about sending control sequences as commands on the Terminal Control Sequences page.

# Editor Integration

Attribute Usage
data-filename Filename to perform action against.
data-target Perform action with the text against the file based on filename:
- replace: Replace contents of the file
- prepend: Add to the start of the file
- append: Add to the end of the file
- insert: Support for a replacing based on
data-marker For use with data-target insert. Replaces a string matching the marker (e.g. #TODO-insert) with the code snippet provided.

# Target Examples

# Replace Target
<pre class="file" data-filename="app.js" data-target="replace">var http = require('http');
var requestListener = function (req, res) {
  res.writeHead(200);
  res.end('Hello, World!');
}

var server = http.createServer(requestListener);
server.listen(3000, function() { console.log("Listening on port 3000")});
</pre>
# Insert Target

The existing app.js file must include the text #TODO-insert where the console.log to appear.

<pre class="file" data-filename="app.js" data-target="insert"  data-marker="#TODO-insert">console.log("Hello World")</pre>

https://katacoda.com/scenario-examples/courses/uilayouts/uilayout-editor-terminal

# Clipboard Target
<pre class="file" data-target="clipboard">TestP@ssw0rd</pre>

# Clipboard Integration

https://katacoda.com/scenario-examples/scenarios/clipboard

# Displaying Images

https://katacoda.com/scenario-examples/scenarios/displaying-images

# Displaying Videos

https://katacoda.com/scenario-examples/scenarios/embed-videos

# Syntax Highlighting

Katacoda has incorporated HighlightJS to automatically provide syntax highlighting on any code snippets wrapped in HTML <pre></pre> tags.

Syntax highlighting is not applied to Markdown code blocks at this time.

# Understanding Katacoda's index.json

# Root Elements

Element Description
title Title for the scenario.
description Description for the scenario.
difficulty Difficulty for the scenario shown on the intro screen. Optional
time Time for the scenario shown on the intro screen. Optional
icon Icon to use when displaying the scenario panel on Katacoda.com. Optional
details Steps, intro and finish text to display. More Info
files What files to automatically open when using editor-terminal layout.
environment Configure the UI for the scenario. More Info
backend Define the environment for the scenario. More Info
private Set to true if you want to make the scenario only accessible via the Embed API or to other members of your organization within Katacoda.

# Details

Element Description
steps Array of steps for scenario. More Info
intro Details for the intro screen. More Info
finish Details for the finish screen. More Info
assets List of files to upload. More Info

# Intro / Finish / Steps

Element Description
title Title text for the step.
text File of the Markdown file to display.
answer Display an additional Solution screen on the step.
verify Run a script to verify if the user can proceed. Exit code should be 0 to allow user to proceed.
background Run script in the background of the terminal session.
foreground Run script in the foreground of the terminal.

# Assets

There are different places where the files can be uploaded, the client and any of the hosts. The client is the container defined in the index.json file. host01 is where Docker itself is running.

To copy all files to the /root folder in the host01 you can use: "assets": { "host01": [ {"file": "*", "target": "/root"} ] }

To copy the file example to the home of the client and to grant execution privileges: "assets": { "client": [{"file": "example", "target": "/root/", "chmod": "+x"}] }

Element Description
file File to upload. Should be within the assets folder in the scenario directory. Wildcard (*) support for uploading multiple files or *.sh for only certain extensions, in this case files with sh extension. For uploading all subdirectories, you can use **/*.*.
target Directory to upload the file too within the environment
chmod Set the "+x" flag if it's a script to be executed. Optional.

Learn more

# Environment

Element Description
uilayout UI Layout to use. View the list of supported layouts.
uieditorpath Default path for editor files. Usually within /root directory.
showide Show VS Code IDE in tab.
showvisualise Show Weave Scope tab.
showdashboard Display additional dashboard links. Required to use dashboards list. If no list provided, the default port from Backend is used.
dashboards https://www.katacoda.com/scenario-examples/scenarios/dashboard-tabs
terminals https://www.katacoda.com/scenario-examples/scenarios/dashboard-tabs
exclusionPatterns Hide certain files/folders from the text editor's tree view. Example is ["*test", "./test/*", "./logs"]. Not supported in VS Code.
hideHiddenFiles Hide hidden files in the text editor's tree view. Not supported in VS Code. Default false.
uisettings Set the syntax highlighting for the text editor. Not supported in VS Code.
hideintro Should the intro screen be shown at the start? Default false.
hidefinish Should the finish screen be accessible? Default false.
hidesidebar Should the scenario step-by-step text be hidden? Default false.

# Backend

Element Description
imageid Specify the environment required for the scenario. View the list of supported environments.
port Optional default port to use for rendering links.

# Complete Example

{
  "title": "Scenario Title",
  "description": "Scenario Description",
  "difficulty": "beginner",
  "time": "5-10 minutes",
  "details": {
    "steps": [
      {
        "title": "Step Title",
        "text": "step1.md",
        "answer": "step1-answer.md",
        "verify": "step1-verify.sh",
        "background": "run-command-in-background.sh",
        "foreground": "run-command-in-terminal.sh"
      },
      {
        "title": "Step 2 - Step Title",
        "text": "step2.md"
      }
    ],
    "intro": {
      "text": "intro.md",
      "background": "courseBase.sh",
      "credits": "",
      "foreground": "changecd.sh"
    },
    "finish": {
      "text": "finish.md"
    },
    "assets": {
      "client": [
        {
          "file": "docker-compose.yml",
          "target": "~/"
        }
      ],
      "host01": [
        {
          "file": "config.yml",
          "target": "~/"
        }
      ]
    }
  },
  "files": [
    "app.js"
  ],
  "environment": {
    "uieditorpath": "/root/example",
    "hideHiddenFiles": true,
    "exclusionPatterns": ["*test", "./test/*", "./logs"],
    "showdashboard": true,
    "dashboards": [{"name": "Tab Name", "port": 80}, {"name": "Tab Name", "port": 8080}],
    "uilayout": "editor-terminal"
  },
  "backend": {
    "imageid": "ubuntu"
  }
}

Any markdown output to the learner can include links that render to be clickable. Links can provide learners with additional information or resources such as technical documentation or topics within O'Reilly books. Avoid links to weak sources that can break in the future. Try to include automated tests that periodically validate these links.

# Displaying 😸 Emojis 🌈

Emojis may appear in the markdown rendering, such as βœ” β˜‘ βœ… πŸŽ‰ πŸ†. A complete list of Unicode Emojis is at unicode.org.