Creating Instructions with Markdown Syntax
Creating Instructions with Markdown Syntax
Updated on 10 Sep 2024 • 23 Minutes to read
If you are using Skillable's native instructions, select Edit Instructions from the lab
profile details screen.
# Heading1
## Heading2
### Heading3
#### Heading4
##### Heading5
###### Heading6
Text Formatting
Text formatting in Markdown allows you to modify the appearance of text, including its
font, size, color, alignment, and style. Here are some key formatting options:
`code block`
```PowerShell
get-service | stop-service -whatif
```
Code Block Modifiers: These change the way code blocks are displayed. They
can be used with or without a language directive. Simply leave out the language
directive and only include the code block modifier. Examples include
Prevents code from being highlighted.
```PowerShell-nocolor
$processes = Get-Process
$sorted = $processes | Sort-Object -Property WS -Descend
$sorted | Select-Object -First 5
```
Prevents the code block from rendering with a tab that displays the
language used.
```PowerShell-notab
$processes = Get-Process
$sorted = $processes | Sort-Object -Property WS -Descen
$sorted | Select-Object -First 5
```
Prevents the code block from being highlighted, no language tab and is not
copyable.
```PowerShell-nocode
$processes = Get-Process
$sorted = $processes | Sort-Object -Property WS -Descen
$sorted | Select-Object -First 5
```
```PowerShell-nocopy
$processes = Get-Process
$sorted = $processes | Sort-Object -Property WS -Descen
$sorted | Select-Object -First 5
```
```PowerShell-wrap
$processes = Get-Process
$sorted = $processes | Sort-Object -Property WS -Descen
$sorted | Select-Object -First 5
```
```PowerShell-linenums
$processes = Get-Process
$sorted = $processes | Sort-Object -Property WS -Descen
$sorted | Select-Object -First 5
```
Page formatting
Page break: Used to separate content into pages. Separating into pages creates a
next button that the student must select to navigate to the next page. This is useful
for displaying small sections of instruction to the student at a time, rather than all
instructions on the same page within the lab. Type three = (equals) symbols on the
line where the current page should end. The new page will begin on the line
following the three = symbols.
===
Horizontal Line: Used to separate content on the same page. Type three --- (dash
or hyphen) on the line where the horizontal line should appear.
---
Block quote: Used to quote information from other sources. Block quote text
appears indented from other content in the document. Type a > (greater-than sign)
before text that should appear in the block quote. Most Markdown syntax will
render inside of block quotes.
Image: Used to embed an image inline with other content. When images are
selected, they will open in a new window and display at the images full resolution.

Image Dimensions: You can specify image dimensions in your lab. Dimension
values are in pixels and are placed inside curly braces, immediately after the end of
the link URL syntax. Height and width are separated by a "x" in this format:
{widthxheight}
It's also possible to simply supply the width: {width}. In this case, the height is
automatically calculated for you to be proportional to the provided width.
Video: Used to embed a video inline with other content. The syntax format should
look the same as an image, except the video should begin the word VIDEO (all caps).
Videos are used to provide rich media content, such as short, step-specific
videos, that can serve a variety of purposes: to demonstrate a series of steps, to
assist visual learners, to provide clarity, to provide additional information and
others. Videos showing the steps in the task are particularly useful for difficult
and complex tasks as well.
The video can be any URL that points to a video. Videos that are hosted on
YouTube will be embedded in the lab instructions, and do not need to open in a
separate window, for the video to play. Alternatively, you can link videos hosted
by other sources in the lab instructions, using Markdown syntax.
The following are some guidelines for creating videos that are associated with lab
tasks:
Keep the video short, between 30 – 60 seconds at most.
Make sure the video covers only the relevant step.
!video[text to display](url)
Audio: Used to embed an inline audio player, or a link to an audio recording.The
syntax format should look the same as a video, except the audio should begin with
a ! (explanation mark), followed by the word audio.
!audio[text to display](url)
Image with link: Used to embed an image that can be selected to navigate to a
specific URL (internal or external).
[](url "Optional link title")
Portal Link: used to launch a hyperlink. In the Cloud Client, this will open the
hyperlink in the left window (Resource Portal). In the traditional virtualization client
(vm-based labs), this will open the hyperlink in a new local browser window.
<[text to display](URL)
Image Link: used to display a link with a camera icon, to suggest that the hyperlink
opens an image. Opens in a new window.
Video Link: used to display a link with a video camera icon, to suggest that the
hyperlink opens a video. Opens in a new window.
- [] Item 1
- [] Item 2
- [] Item 3
- [] Item 4
- [] Item 5
1. [] Item 1
1. [] Item 2
1. [] Item 3
1. [] Item 4
1. [] Item 5
Table formatting
Tables can be aligned left, right or center by placing a : (colon) on the head row of
the table. Placing a colon on the left side, right side or both sides of the dashes in
the header row, will align the text in the table accordingly.
Left-aligned text
| column 1 | column 2 |
|:---------|:---------|
| data 1 | data 2 |
| data 3 | data 4 |
Right-aligned text
| column 1 | column 2 |
|---------:|---------:|
| data 1 | data 2 |
| data 3 | data 4 |
Center-aligned text
Plain text Copy
| column 1 | column 2 |
|:--------:|:--------:|
| data 1 | data 2 |
| data 3 | data 4 |
Link formatting
Knowledge
You should enter alt text and title to the link, so that when a user mouses over it, a
description will appear. You can add alt text and a title with the following syntax:
!IMAGE[image alt text](Image.jpg "image title text")
Internal link: Used to link to a specific section within a document. Internal links
must be all lower-case, alphanumeric and separated by hyphens. Any characters
that are not alphanumeric should be omitted, and spaces should be replaced with a
hyphen.
remove anything that is not a letter, number, space or hyphen
changes any space to a hyphen.
If that is not unique, add "-1", "-2", "-3",... to make it unique
Relative link: used to link to a page in the same directory without the need to
display the full URL of the page.
Reference link: used to provide a link that will be referenced multiple times. The
link can be referenced by typing the text value between the [ ] (square brackets). It
is not necessary to include the full URL, as long as the text value in both sets of
brackets is the same.
Text lookup:
Label lookup:
[Reference link][Name of URL]
[Name of URL]: URL "Optional link title"
Footnote style:
[Reference link][1]
[1]: URL "Optional link title"
Help Link: used to provide a link that will help the student with the section of the
lab they are working on.
Plain text Copy
Hint Link: used to provide a hint that will help the student with the section of the
lab they are working on. This is most effective as a dialog (see Link Behavior
Prefixes).
Plain text Copy
Knowledge Link: used to provide a link, that will give the student additional
knowledge about with the section of the lab they are working on.
Plain text Copy
^[link text](https://URL.com)
Open in portal window (or a new window if there is no portal window): used to
open a link in a Portal window of the lab, or a new window if there is no portal
window in the lab.
<[link text](https://URL.com)
Open in a New Window: used top open a link in a new window.
[link text](https://URL.com)
Special formatting
Variables: Used to store information that is not known at the time of lab authoring.
Variables use Replacement tokens; @lab.textbox(name), @lab.Variable(name)
and @MaskedTextBox(name).
Use @lab.texbox(name) to define the variable in the (name).
Use @lab.Variable(name) to recall the information store in the variable. For
example, you could create a variable with @lab.textbox(studentPassword) and
ask the student to enter a password in the field. Later in the lab you could call
back the student's password with @lab.Variable(studentPassword). This
prevents the student from having to remember or write down their password,
since it is stored in the lab by a variable.
Defining Variable in lab instruction editor view:
Defining the variable in the lab from student view in the lab:
The password is recalled in later lab steps using the Replacement Token below
Calling Variable in lab instruction editor view:
Knowledge
Masked Textboxes only obscures the text of the password from view. It does not
encrypt the text that is entered into the textbox.
- Defining the password as a variable in the lab from the student view:
- The student enters their password into the Masked textbox in the lab instructions:

:::
Key Combo: used to generate a button that sends a combination of key codes to
the active VM. The key codes used are standard JavaScript event key codes.
Characters supported for key combo labels include: A-Z, 0-9, underscore, dash and
plus. Other special characters will not work.
Some key codes may not function as expected when using vSphere. It is highly
recommended to test each key combo before publishing the lab instructions
for production use.
> @lab.KeyCombo(label)[keyCode1,keyCode2].
Dialog: Used to open a dialog popup, to display additional information. This can be
useful to make additional information available to the student. Dialogs should not
be used to display websites that are in an iFrame, as this can cause some
abnormal page rendering in the dialog.
>[Reference Link]:
^instructions[text](url)
Note
The best practise when creating multiple page instructions is to define the
reference content at the beginning of the first page, this way it can be
referenced on all pages, this approach can save siginificant time when defining
a page header and/or footer.
Define content
Reference Content
!instructions[][label]
Commands: Used to target the current resource in the Resource Portal to input
commands. To mitigate risk of error and to enhance the overall experience of the
lab, the IDLx platform supports executing commands directly in the area of focus of
the Resource Portal. Selecting the text in the lab instructions will input the
command into the item in focus, on the Resource Portal. Commands can be a single
line (shown below) or multi-line.
There are 4 different kinds of commands that you can configure:
Type Text. This is not a command per se. Rather, this command type allows the
user to input a predetermined string. To use this, simply add +++ on each side
of the text that you wish to have typed.
PowerShell. This allows the user to execute a PowerShell command in the
background. The user does not see the execution of the command. To use this,
simply add {PowerShell} to the end of the command.
PowerShell with UI. This opens a command prompt window in the VM and
shows the command execution. To use this, simply add {PowerShell visible}
to the end of the command.
Shell. This causes a command to be executed in the background. The user does
not see the execution of the command. To use this, simply add {Shell} to the
end of the command.
Shell with UI. This command opens a command prompt window in the VM and
shows the command execution. To use this, simply add {Shell visible} to
the end of the command.
Commands require Integration Services to be installed on the VM. After installing
Integration Services, you must save a differencing disk for Integration Services to be
installed on all future launches of the lab.
@[Text to display](`command`)
@[Text to display][multi-line-command]
Multi-line-command-id:
```
Multi-line-command-id
Command-goes-here
```
Below is an example of how a multi line command would look for a PowerShell cmdlet,
with no UI. Shell commands can be executed the same way, by replacing PowerShell
with Shell .
[Get Service]:
```PowerShell
get-service | stop-service -whatif
```
Knowledge
PowerShell commands are executed in a CMD prompt, in the lab. The command
will still function as intended.
Commands can perform any action that is possible to do from a command or Windows
PowerShell prompt. For example, the command could open File Explorer at a particular
location within a directory structure, open dialog boxes, start scripts, open documents
and web pages, and many others.
Knowledge
When using the command prompt to run commands that are not in the command
path, and have spaces in their fully qualified name, they need special attention.
For
example if there is a requirement to run MSEdge (C:\Program Files
(x86)\Microsoft\Edge\Applications\msedge.exe), this will not work as expected
surrounded by double > quotes. To run this type of command either proceed the
command with an & or use the PowerShell Start-Process command, as per these
examples:
@[Text to display](`& "c:\program files
(x86)\microsoft\edge\application\msedge.exe"`){shell}
Or
@[Text to display](`Start-Process "c:\program files
(x86)\microsoft\edge\application\msedge.exe"`){PowerShell}
Although potentially any task could be reduced to an action that can be executed as a
command shell or Windows PowerShell command, you should use this feature
judiciously. Users should still know how to open File Explorer and perform other basic
actions. This feature is most useful for a complex task that involves numerous steps,
opening file locations deep down in directory structures, opening specific Web pages,
and other similar activities.
Include: Used to input text from a GitHub raw link. This is useful to use to pull in
content hosted on GitHub. Navigate to the GitHub page containing the content to be
used, select the Raw button, then copy the URL of that page and include it in the
below syntax.
Note: GitHub hosted content can be changed by the repo maintainer of the
content and will change the instructions displayed in the lab that is using the
Include syntax.
[!include [label](url)]
Copyable Text: Used to make text copy to the local clipboard when the student
selects the text. Type two + (plus) symbols on each side of the text that should be
made copyable.
++copyable text++
Type Text: Used to input text into the current cursor location inside of a managed
virtual machine showing in the Resource Portal. Selecting the text in the lab
instructions will automatically type the text into the managed virtual machine. When
authoring lab instructions, use three + (plus) symbols on each side of text to convert
it into Type Text.
+++Type Text+++
Copyable and Type Text: used to make text copy to the local clipboard and type
into a virtual machine when the student selects the text. Type four + (plus) symbols
on each side of the text that should be made copyable and type text.
Embed YouTube video: Used to embed a YouTube video inline with the lab
instructions. URLs from YouTube.com automatically embed. Videos from any other
URL will not embed.
!video[text to display](url)
Replacement Token: Used to replace text with a variable that is unknown at the
time of authoring the lab. The value of these variables may not be generated or
created until the lab is launched by the student. These can include usernames, user
first name, user last name, running lab instance ID number, etc.
Replacement tokens use the syntax @lab.replacementTokenName. You can see the
list of all @lab replacement tokens available to your lab by simply editing the
instructions, and selecting the @lab button.
Lab Replacement
Description
Token
@lab.Activity(Autom
Inserts activity Automated1 into the instructions.
ated1)
@lab.Activity(Quest
Inserts activity Question1 into the instructions.
ion1)
@lab.LabInstance.I
The unique ID of the running lab instance.
d
@lab.LabInstance.Gl
The globally unique ID of the running lab instance.
obalId
@lab.User.Organizat
The name of the organization the user belongs to.
ion.Name
@lab.VirtualMachine
Inline console for the VirtualMachineName virtual
(VirtualMachineName)
machine.
.Console
@lab.Container(cont
Terminal for (containerName)
ainerName).Terminal
@lab.Container(cont
@lab.Container(cont
@lab.Container(cont
@lab.Container(alia
The web display URL for container (alias).
s).WebDisplayUrl
@lab.CloudSubscript The name of the subscription the lab is launched
ion.Name against.
@lab.CloudSubscript The tenant name of the subscription the lab is
ion.TenantName launched against.
@lab.CloudResourceG The instance name of the ResourceGroup1
roup(1).Name resource group.
@lab.CloudResourceG
The instance name of the (StackName) resource
roup(StackName).Nam
group. This applies to AWS only
e
@lab.CloudResourceG
The cloud platform region/location where
roup(StackName).Loca
(StackName) resources are deployed.
tion
@lab.CloudResourceT
@lab.CloudResourceT
@lab.CloudResourceT
A deployment URL for the VNET resource
emplate(Template1).D
(rendered as text, not a link).
eploymentUrl
@lab.CloudResourceT
@lab.CloudPortalCre
The username of the User1 cloud portal user
dential(User1).Usern
account.
ame
@lab.CloudPortalCre
The password of the User1 cloud portal user
dential(User1).Passw
account.
ord
@lab.CloudCredentia
The Username assigned from the PoolName
l(PoolName).Usernam
credential pool.
e
@lab.CloudCredentia
The Password assigned from the PoolName
l(PoolName).Passwor
credential pool.
d
@lab.CloudCredentia
The TenantName assigned from the PoolName
l(PoolName).TenantNa
credential pool.
me
@lab.CloudCredentia
The TenantPrefix assigned from the PoolName
l(PoolName).TenantPr
credential pool.
efix
@lab.CloudPortal.Li
A link to the cloud portal.
nk
@lab.CloudPortal.Ur
The cloud portal URL (rendered as text, not a link).
l
@lab.CloudPortal.Si
A cloud portal sign-in link.
gnInLink
A larger essay style text box that can hold up to
5000 characters. Height in number of lines
@lab.EssayTextBox(n
declared by [height] is optional. This variable
ame)[height]
value can then be displayed elsewhere using
@lab.Variable(name) .