Instructions Editor

Prev Next

Lab Instructions are designed for hands-on labs to guide learners as they work within the lab environment.

This article describes the features available in the Instructions Editor and explain how to use them. The Skillable Studio Visual Instructions Editor is a versatile and powerful Markdown editor. It supports both Code (Markdown) mode and Visual mode, making it easy to switch between writing in plain text and a more visual format.

Editor Key Features

  • Visual Mode: Write documents in Visual mode with ease using common editing tools. There’s no need to know Markdown to create great lab content.

  • Live Preview: Write instructions in Markdown and see a live preview of the formatted text with the Learner Preview pane.

  • Syntax Highlighting: Easily read and write code.

  • Scroll-Sync: Keep your editor and preview in sync as you scroll.

  • Spell Checker: Enable spellcheck capabilities for Visual mode.

  • Drag and Drop: Simply drag and drop tokens, variables, and Activities right into the Editor.

  • Clickable Content Objects: Double-click action objects in Visual mode to quickly edit in a modal dialog, without Markdown.

Switch to the Visual Instructions Editor

The Visual Instructions Editor is a robust tool for creating and editing lab instructions. To open Visual mode, select the Visual toggle in the bottom-left corner. To return to Code (Markdown) mode, select the Code toggle. By default, the Editor opens in Code mode, but you can use the Editor’s Settings to change the default to Visual mode instead.

Switching to Visual Mode for the First Time

When you first switch to Visual mode, you’re asked to confirm the change. You’ll see two confirmations:

  1. A dialog asking if you want to proceed.

  2. A review prompt with Approve (to stay in Visual mode) or Revert (to return to Code mode).

You’ll only need to approve these changes once for each Instructions Set.

Features of the Visual Instructions Editor

  1. Ribbon Bar: Apply general formatting, layout, paragraph formatting, and power tools.

  2. Left Action Panel: Effortlessly work with all of Skillable’s specialized features, including Lab Tokens, Lab Activities, Replacement Tokens, and Swap Text.

  3. Top Menu Bar: Use the Editor tab, Activities tab, Help tab, Settings menu, and the Instructions Set dropdown menu to customize your instructions.

  4. Bottom Bar: Switch between Visual and Code mode, and control the Autosave toggle (or save your changes manually).

  5. Learner Preview: Update the lab’s theme and see a live preview of the instructions as they would show for a learner.

Ribbon Bar Features

General Formatting

Button

Item

Description

Key Combo

btn-Bold

Bold

Adds bold emphasis to selected text. Use this to emphasize important words or phrases.

Ctrl+B

btn-Italic

Italic

Adds italic emphasis selected text. This is often used for emphasis or to denote titles of works.

Ctrl+I

btn-Strike

Strike

Adds a strikethrough to selected text. This can be useful for showing deletions or changes.

Ctrl+Shift+X

btn-Heading

Heading
btn-HeadingExpand

Changes the selected text to a heading. Headings are used to organize content into sections.

btn-Blocks

Blocks
btn-BlocksExpand

Formats the selected text as a block element, such as a blockquote or Skillable special formatting. Special formatting is predefined when you select (Alert, Note, Help, Hint, and Knowledge blocks).

btn-Links

Links

Adds a hyperlink to the selected text. This is useful for linking to external resources or other parts of the document.

Ctrl+K

btn-Code

Code
btn-CodeExpand

Formats the selected text as code.

Code Sample: Typically used for multi-line code with syntax highlighting based on the defined language that is being used.

Inline Code Sample: Used to designate a small snippet as a code element with no syntax highlighting.

Code Sample:
Ctrl+Shift+P

Inline Code Sample:
Ctrl+Shift+C

Layout and Paragraph

Button

Item

Description

Key Combo

btn-BulletedList

Bulleted List

Formats the selected text with a bullet list style. Each line in a multi-line selection will have a bullet.

Ctrl+U

btn-NumberedList

Numbered List

Formats the selected text with a numbered list style. Each line in a multi-line selection will be numbered starting from 1.

Ctrl+O

btn-Task

Task List

Formats the selected text with an unordered task list style. Each line in a multi-line selection will have a task checkbox. Task lists can be created by first creating an ordered (numbered) list, then highlighting the list and then selecting the Task list button from the ribbon bar.

btn-DecreaseIndent

Decrease Indent

Outdents the selected sub-elements one level within the context of a Bulleted List, Numbered List, or Task List. Multiple clicks allow only one level outdent from its parent.

Shift+Tab

btn-IncreaseIndent

Increase Indent

Indents the selected sub-elements one level within the context of a Bulleted List, Numbered List, or Task List. Multiple clicks allow only one level indent from its parent.

Tab

btn-Insert

Insert

Inserts page-level objects like Page Break, Section, and Horizontal Rule at the current cursor position.

Horizontal Rule: Ctrl+L

btn-Table

Table
btn-TableExpand

Opens the table menu for inserting tables.

Powertools

Button

Item

Description

btn-AI

AI
btn-AIExpand

  • AI Menu: Provides a chat prompt with options to teach, show steps, quiz, or find resources on a topic, using AI.

  • AI Chat: Offers a chat-style interface based on the provided topic.

  • AI Generated Content: Introduces four tags (ai-teach, ai-show, ai-quiz, ai-resources) for AI-generated content. These content tags generate specific content types directly, simplifying the creation process.

btn-TypeText

Type Text

Inserts Type Text tokens at the cursor’s current position, streamlining the content creation process. There are three variations:

  • Type Text: The text is typed directly into the user environment.

  • Copyable Text: The text is copied to the user’s clipboard.

  • Copy & Type Text: The text is both typed into the user environment and copied to the user’s clipboard.

btn-InputField

Input Field

Inserts various input field types as tokens within the Visual Instructions Editor. Input types include:

  • Text Box: Inserts a text box token.

  • Essay Text: Inserts an essay text box token, with a draggable corner to adjust the number of visible lines, the default number of lines to reveal is user definable using the Modal.

  • Masked Text Box: Inserts a masked text box token for sensitive information.

  • Dropdown List: Inserts a dropdown list token with predefined options.

btn-AuthorComment

Author Comment

Inserts a comment section. The modal popup provides an intuitive way to add comments, with or without selected text, while preserving existing content.

btn-IncludeInstructions

Include Instructions

Provides a versatile way to incorporate external instructions into your lab content. You can include both external instructions and references to instructions defined in the current Instruction Set.

Import from File(s)

Imports content from a file to your current instruction set. Supported file types include: Microsoft Word (.doc or .docx), Markdown (.md), and RTF (.rtf).

Upload Media

Easily insert images, videos, and audio without pasting them into the editor. The dialog box supports drag-and-drop for multiple files and offers options to display files inline or as links, and to overwrite existing files.

Additional AI Information

AI Menu

AI Menu provides a chat prompt to the user with instructions, commonly used to wrap text with syntax that serves as a topic. The text of the link is the topic (e.g., Azure Storage Accounts). Selecting the link displays a menu with four options:

  1. Teach me: Generates a text response designed to teach the learner about the provided topic.

  2. Show me: Generates a list of steps on how to perform the topic, which is useful if the topic text starts with a verb (e.g., "Create an Azure Storage Account").

  3. Quiz me: Generates multiple choice questions on the topic. Attempts to process responses interactively, providing Correct or Sorry, try again feedback based on the answer.

  4. Find Resources: Generates a list of links to web resources about the topic.

AI Chat

AI Chat: Provides a chat-style interface to the user based on the provided topic.

AI Generated Content

Overview: Expands on AI features with four tags that leverage AI to respond to a given topic and format the output according to the specified format:

  • ai-teach

  • ai-show

  • ai-quiz

  • ai-resources

AI Content Tags: These tags (ai-teach, ai-show, ai-quiz, and ai-resources) are designed to generate specific types of content directly, without needing an intermediary selection menu. They allow content creators to specify the type of AI-generated content required at any point in their documents, simplifying the creation process.

Left Actions Panel

LeftBar

Button

Item

Description

btnTokens

Tokens

Create dynamic text placeholders that enhance your lab's interactivity and personalization.

btnActivities

Activities

Provide interactive lab instructions and environments when used for scoring.

btnVariables

Variables

Personalize and fine-tune your lab like never before.

btnTextSwap

Text Swap

Seamlessly change what users see in your lab without altering the actual content.

Functions within Left Actions Panel

Item

Description

Text Search

Allows users to easily start typing and search text within the token name or description and present the corresponding token cards.

Filter

Quickly filters based on available groups.

Search Results

Displays a results message to indicate how many cards are filtered of the total available.

Drag Icon

Allows a user to drag and drop the token card into the editor.

Hovering over Card

Highlights where in the instructions the token is inserted.

Top Menu Bar

Button

Item

Description

TopMenuBarEditor

Editor

Displays the Editor screen.

TopMenuBarActivities

Activities

Displays the Activities Manager screen.

TopMenuBarHelp

Help

Allows users to easily navigate to the help documentation.

TopMenuBarSettings

Settings

Allows users to configure Editor Settings and Lab Options. The available options depend on your Editor mode. For example, Code Editor-specific settings are only visible when you’re in Code mode.

For more information, see the section for Editor Settings.

TopMenuBarInstructionSets

Instruction Sets

Allows user to easily switch between different Instructions Sets while staying in the editor. There is also an option to Manage Instructions Sets.
TopMenuBarInstructionSetsExpand

TopMenuBarClose

Close

Closes the Instructions Editor.

Bottom Bar

BottomBar

Button

Item

Description

BottomBarEditorMode

Editor

Allows users to easily switch between Visual mode and Code mode.

BottomBarAutosave

Autosave

By default, this option is toggled On when editing and auto saves your changes. Once toggled Off, you can manually select Save Changes.

BottomBarSaveChanges

Save Changes

By default, this option is toggled Off when editing. If Autosave is toggled to Off, you can manually select Save Changes.

Editor Settings

Setting

Description

Visual Mode

Code Mode

Learner Preview

Displays a preview of the lab instructions next to the code view, which updates in real time as changes are made to the lab instructions.

Sync Learner Preview Location

Syncs the position of the code view and position of the lab instructions preview while scrolling in the lab instructions editor.

Set Visual Editor as Default

Sets the Visual Editor as the default editor.

Spellcheck

Checks spelling as you write instructions, highlighting potential errors and suggesting corrections.

Code Editor Word Wrap

Allows text to wrap to the next line when it reaches the end of line in the editor pane.

Code Editor Zoom

Adjusts the zoom level while viewing the editor.

Track Task Progress

Displays a progress bar at the bottom of the lab instruction window with the total number of tasks the lab user has to complete. When they check a task, the progress bar reflects their progress.

Require tasks to be completed in order

Requires lab users to complete tasks in the order they appear in the lab instructions.

Auto-Check Previous Tasks

Allows a lab user to select a task in the lab instructions to automatically mark all previous tasks as complete.

Learner Preview

If enabled, the learner preview displays a pane to the right of the Editor that shows how instructions will appear to learner’s. This is what a typical user sees when they launch a lab. Providing a live preview speeds up the content creation process.

To enable or disable Learner Preview:

  1. Along the top of the editor, select the gear icon to open the Settings menu.

  2. Toggle Learner Preview on or off and then click anywhere on the screen to close out of the settings menu.

Frequently Asked Questions

What happens when I add in Markdown the Visual Editor can’t render?

Sometimes there are certain Markdown patterns that users can add to Code mode that Visual mode cannot display properly. In this case, a popup displays indicating that the Visual Editor is currently disabled. No worries, you’re automatically redirected back to Code mode, and Visual mode is disabled to prevent any issues with editing. You will always have an editor that allows you to work effectively.

VisualEditorNotAvailable

Can I change my default editor?

If your lab has some advanced or unique patterns that Visual mode can’t render properly, you can change the default editor mode.

You may also prefer to write your lab instructions in Markdown, using Code mode as the default option. To enable Code mode as the default, use the Settings menu to toggle Set Visual Editor as Default off.

To reset to Visual mode, toggle Set Visual Editor as Default on.

What are Tokens?

Tokens, also known as Replacement Tokens, are dynamic text placeholders that enhance your lab's interactivity and personalization. By inserting structured text (of the format @lab.TokenName) into instructions or scripts, it will dynamically be replaced in each lab launch with personalized text or interactive components like user-specific names, unique identifiers, questions, or dropdown menus. Tokens empower you to create engaging, personalized, and ever-changing lab experiences, fostering interaction and customization for a more immersive skills journey. For more information about Replacement Tokens, read our Replacement Tokens documentation.

TokensPane

What are Activities?

Activities provide ways for users to interact with lab content. Activities also allow authors to assess how well a user is doing in their lab. Activities can consist of interactive questions, automated scripts, or even groups of multiple activities.

You can reference activities in your instructions by using the activity's Alias. For example, if you have a question with the alias "q1", you can reference it in your instructions like this: @lab.Activity(q1). When a learner reaches this point in the instructions, they will see the question you created. For more information about Activities, read our Activities documentation.

What are Variables?

Variables empower you to personalize and fine-tune your lab like never before. Think of them as dynamic settings that you control, allowing you to tailor each launch to your exact needs. While some variables could be as simple as 'Personalized: Yes/No,' others might be complex like SSH keys or completely unique identifiers. This customization injects dynamism into your lab, making every instance distinctive and precisely suited to your requirements. For more information about Variables, read our Variables documentation.

What is Text Swap?

Text Swap empowers you to seamlessly change what users see in your lab without altering the actual content. Just like using find/replace in documents, Text Swap allows you to transform visible text elements while keeping the original text unchanged. For instance, you can transform 'Sign in to the environment' to 'Login' for users, while preserving the original wording for backend operations. Whether you need case-sensitive changes, case-insensitive adjustments, or even more intricate transformations using regular expressions (Regex), Text Swap provides a user-friendly solution to enhance the user experience.