# 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

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"
  }
}

# Providing Links

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.