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
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 </br> - 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>
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:

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.