Using the Markdown Editor

The markdown editor is where you write the instructional content that learners see in the Instructions panel. It provides a rich formatting toolbar, multiple view modes, and tools for embedding interactive activities.

Note

You must select a page in the sidebar before you can edit its content.

Editor Interface

View Modes

Control how you see your content while editing using the view mode buttons in the top-right corner.

Available modes:

• Editor: Raw markdown editing with syntax highlighting
• Preview: See how content will appear to learners
• Side-by-side: Edit and preview simultaneously

The side-by-side mode is particularly useful for checking formatting as you write, ensuring your content looks exactly as you intend before saving.

Fullscreen Mode

Click the fullscreen button to hide the outline sidebar and maximize your editing space. This is useful when working with long content or complex formatting.

Toolbar Features

The toolbar provides quick access to formatting tools and content insertion options.

Text Formatting

Button	Function	Result
B	Bold text	**bold**
I	Italic text	*italic*
S	Strikethrough	~~struck~~

Headings

Button	Creates	Markdown
H1	Level 1 heading	# Heading
H2	Level 2 heading	## Heading
H3	Level 3 heading	### Heading

Use headings to structure your content hierarchically, with H1 for main topics, H2 for major sections, and H3 for subsections.

Code

The Code button behavior depends on your selection:

• With text selected: Wraps the text in backticks for inline code formatting like npm install
• Without text selected: Inserts a multi-line code block with syntax highlighting

Code block syntax

There are two equivalent ways to write a multi-line code block. The common form is a fenced code block with a language and optional comma-separated flags:

```bash
echo "Hello, World!"
```

The <instruqt-code> component is equivalent. You only need it when you want the line-numbers-start option, which a fenced block cannot express:

<instruqt-code language="bash">
echo "Hello, World!"
</instruqt-code>

The editor writes fenced blocks by default and switches to <instruqt-code> automatically when it needs to, so you can use whichever form you prefer.

Runnable code blocks

Add the run flag to make a code block executable. Learners see a run button on the block; clicking it sends the command to a terminal in the lab and runs it, so they don’t have to copy and paste.

```bash,run
echo "Hello from the terminal"
```

The same block using the component form:

<instruqt-code language="bash" run>
echo "Hello from the terminal"
</instruqt-code>

When using flags in a fenced block, the language must come first: write ```bash,run, not ```run. Without a language, run is read as the language name and the block will not be runnable.

Note

The run button is enabled only when the lab layout includes a terminal. If no terminal is available, the button is disabled and its tooltip asks the learner to switch to a terminal tab. When the layout has more than one terminal, clicking run opens a menu so the learner can choose which terminal to run the command in. There is no way to pre-select a target terminal from the markdown.

Code block options

Combine options in a fenced block by separating them with commas (for example bash,run,line-numbers,wrap), or set them as attributes on <instruqt-code>.

Option	Fenced flag	Component attribute	Description
Language	first segment	language="bash"	Language for syntax highlighting and the block’s language label
Run	run	run	Shows the run button to execute the code in a terminal
Line numbers	line-numbers	line-numbers	Shows line numbers in the left gutter
Starting line number	not available	line-numbers-start="10"	Number of the first line; requires the <instruqt-code> form
Word wrap	wrap	wrap	Wraps long lines instead of scrolling horizontally
Hide copy button	nocopy	no-copy	Hides the copy-to-clipboard button (shown by default)

Caution

The hide-copy option is spelled differently in each form: nocopy (no hyphen) as a fenced flag, no-copy (hyphenated) as a component attribute.

Example combining several options:

```javascript,run,line-numbers,wrap
const message = "This is a long line that wraps instead of scrolling horizontally.";
console.log(message);
```

Code groups

Group related code blocks into a single tabbed view with <instruqt-code-group>. Give each block a title to label its tab; individual blocks can still use run and the other options:

<instruqt-code-group>
  <instruqt-code language="bash" title="macOS / Linux" run>
  brew install mytool
  </instruqt-code>
  <instruqt-code language="powershell" title="Windows">
  choco install mytool
  </instruqt-code>
</instruqt-code-group>

Lists

• Unordered lists (ul): Bullet-point lists for unordered items
• Ordered lists (ol): Numbered lists for sequential steps

Example:

- Bullet list item
- Another item

1. Numbered list
2. Second item

Links

Insert hyperlinks to external resources or internal cross-references. The link button opens a dialog for URL and display text.

Example:

[Link text](https://example.com)

Tables

Create formatted tables using the table insertion tool. Tables are useful for structured data, comparisons, or feature lists.

Example:

| Column 1 | Column 2 |
| -------- | -------- |
| Data 1   | Data 2   |

Assets

The Assets button opens a picker showing all uploaded lab assets. Select any asset to insert appropriate markdown:

Asset Type	Inserted As
Images (PNG, JPG, GIF)	Markdown image tag: 
PDFs	PDF viewer component: <instruqt-pdf>
Videos	Video player component: <instruqt-video>
Other files	Download link: <a href="path">

Help

Click the ? button to open the Markdown Cheatsheet in a new tab. This external reference provides quick syntax reminders for markdown formatting.

Embedding Activities

Tasks

Click the Tasks button to embed interactive task activities in your content.

The picker shows:

• Existing tasks: Select any previously created task to insert
• Create new task: Open the task creation drawer to build a new task

Once inserted, the task appears as a self-closing tag:

<instruqt-task id="task_id" />

The task ID must match a task defined in your Activities section.

Quizzes

Click the Quizzes button to embed quiz activities in your content.

The picker shows:

• Existing quizzes: Select any previously created quiz to insert
• Create new quiz: Open the quiz creation drawer to build a new quiz

Once inserted, the quiz appears as a self-closing tag:

<instruqt-quiz id="quiz_id" />

The quiz ID must match a quiz defined in your Activities section. To learn more about activities, you can go to the Activities page.

Tip

Position activities after the instructional content that prepares learners for them. This ensures learners have the context they need before attempting the activity.

Saving Changes

Content Changes vs. Structural Changes

The Instructions tab handles saves differently based on what you’re changing:

Content changes (require manual save):

• Editing page markdown content
• Modifying text, formatting, or embedded activities

When you make content changes, the Add changes button appears next to Discard.

Structural changes (saved immediately):

• Creating, renaming, or deleting chapters and pages
• Reordering chapters or pages
• Moving pages between chapters

These changes take effect immediately without requiring Add changes.

Best Practices

1. Clear Hierarchy: Use heading levels consistently (H1 for title, H2 for sections, H3 for subsections)
2. Break Content Up: Use headings to create scannable sections rather than long blocks of text
3. Preview Frequently: Switch to preview mode to see how learners will experience your content
4. Activity Placement: Embed activities after relevant instructional content, not before
5. Save Regularly: Use Add changes frequently to avoid losing work
6. Descriptive Links: Use meaningful link text instead of “click here”

Summary

The markdown editor provides powerful tools for creating engaging instructional content. Master the toolbar features, view modes, and save workflows to efficiently produce high-quality lab content.

Key points:

• Select a page before editing its content
• Three view modes: editor, preview, and side-by-side
• Toolbar provides formatting tools, asset insertion, and activity embedding
• Content changes require Add changes, structural changes save immediately
• Review changes interface provides selective discard with git-style diff
• Activities (tasks and quizzes) can be inserted from existing or created new via drawer

Related Documentation

• Managing Chapters & Pages: Learn about content organization
• Creating Activities: Build tasks and quizzes to embed
• Designing Layouts: Control how content appears to learners