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 terminal.

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

`top`{{execute}}

If you wish the command to be run in a separate 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 tabs to be reused for certain actions.

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 wrapped in HTML <pre></pre> tags.

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

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.