Markdown Syntax

Markdown is the lightweight markup language used to author interactive content. More specifically, lab steps and challenge tasks are written in GitHub-flavored Markdown with the help of markup extensions to incorporate additional UI capabilities as described in the following sections.

UI Shortcuts

Labs use UI shortcuts to help the learner focus on the topic instead of copying long commands. These are optional, but encouraged, and it is up to the author’s discretion to use shortcuts when appropriate.

Execute

Applying the execute class will make any code snippet executable within the current terminal.

This can be added to any code snippet, for example:

`top`{{execute}}

This also works with “fenced” multi-line code blocks:

```
  cd example &&
    npm install
```{{execute}}

If you wish the command to be run in a specific terminal tab, include T#, where # is the tab number. For example, if you were wanting to target the second terminal, you might run:

`sh some_file.sh`{{execute T2}}

This allows certain terminal tabs to be reused for certain actions, or allows a long-running command such as development servers to run in a secondary tab.

When using {{execute T2}}, you will want to make sure the next command for the first terminal use T1 to switch back to the first terminal. Otherwise, {{execute}} without a terminal number will continue using the currently selected terminal tab. If you anticipate a user jumping around to rerun previous commands, you may want to add an explicit T1 to prior code blocks as well.

Interrupt

When using execute, you can include an interrupt class to execute a Ctrl+C, stopping any task that was running previously. This can be useful if the previous commands in the terminal might capture user input, such as top.

This can be added to any code snippet like so:

`top`{{execute interrupt}}

Copy

The use of the copy class will copy whatever is inside the code element to the user’s clipboard. For example:

`top`{{copy}}

Open

Applying an open class will open the specified file in the editor. It can be used as follows:

`myfile.js`{{open}}

Note: O’Reilly style dictates that filenames and filepaths should appear in italic font (e.g., src/index.js), however, for the open command to be applied, code styling must be applied in these instances for the command to be applied correctly.

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.

Clipboard Integration

The following will copy the text into the clipboard. This is useful if users need to interact with a web interface.

docker

Within the Markdown step, you would write:

`docker`{{copy}}

Katacoda supports copying code snippets or longer text into the clipboard by adding the attribute data-target.

This is created by embedded HTML into the Markdown.

<pre class="file" data-target="clipboard">
Copy Me To The Clipboard!!
</pre>

Note that without the class="file" attribute, it will not display the clipboard functionality. For example:

<pre data-target="clipboard">
Not a file
</pre>

won’t work as expected.

Syntax Highlighting

Katacoda has incorporated HighlightJS to automatically provide syntax highlighting on any code snippets marked with a highlight language. We support the core languagues included in the default minified web build.

We have enabled automatic language detection, but we encourage authors to explicitly set the language on all code blocks to ensure the correct highlighting is applied.

The preferred method of highlighting is via markdown code fences with language hints. For example:

```py
from pathlib import Path

p = Path()
```

If you want to highlight <pre> blocks, use the lang="" attribute. For example:

<pre lang="c">
#include <stdio.h>

int main() {
   printf("Hello, World!");
   return 0;
}
</pre>

Example

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

Editor Integration

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>

Clipboard Target

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

Displaying Images

Within the Assets directory, images can be embedded into the scenarios using standard markdown image markup.

For example if a logo-text-with-head.png file exists in the /assets/ directory, and you wanted to embed it in a step, you would do the following:

![Katacoda Logo](./assets/display_img_cat.png)

Note that only images within the Assets directory are available (though linking to external images via URL is supported, though not necessarily recommended, as the URLs of those images may change).

TIP: Images are automatically available to the step markdown so long as they’re in the assets directory, so you don’t need to provide them inside of index.json unless you want the user to be able to access them in the terminal/editor for some reason.