Add a challenge to a track
Make your tracks interactive with challenges.
This guide explains how to add a challenge to a track from Web UI and Instruqt CLI.
A challenge is a task in a track that the learner has to solve. To the learner, a challenge has two screens:

The first screen is the Notes screen, and the second screen is the Assignment screen:
- The Notes screen shows while the challenge is loading.
- The Assignment screen is the hands-on part of a challenge, with a two-pane layout. The left pane lets the learner interact with the sandbox, and the right pane shows the assignment text.
The challenges definition consist of the following parts:
Description
The description defines several challenge settings and the assignment text:Title
Slug
Type
Assignment
This is the assignment text in Markdown. In general, you introduce the challenge here to the learner. And describe what is expected from the learner to solve the challenge.Teaser
Notes
Notes are displayed while a challenge is loading. And are meant to present learning content to the learner. Notes are great to give the learner some introduction. Or to provide background information about your software. You can add notes to a challenge in the following formats:Text
Image
Video
If you chooseText
, you can enter your content in Markdown. If you chooseImage
orVideo
, you can enter the URL of the image or video.Tabs
Tabs define the components that the learner can work with inside a challenge. For example, a Shell terminal or a text editor. You can make the following tab types available:Services
Terminals
Editors
Websites
External apps
Scripts
Scripts execute automatically when specific challenge lifecycle actions occur, like starting a challenge. You use scripts to set up a challenge or check if the learner solved the challenge. You can add the following scripts for a challenge:setup
check
solve
cleanup
See the topics Add a script to check challenge execution and Lifecycle scripts for more information about scripts.
You must have already built a track to which you can add a challenge. Follow the guide Create a track from a template if needed.
Pick the Web UI or the Instruqt CLI route depending on your preference:
🌐 Web UI
💻 Instruqt CLI
- 1.
- 2.Click the TRACK_NAME of the track you want to add a challenge to. ↳ Instruqt shows the corresponding Track overview page.
- 3.Click Add challenge.
- 4.In the Title field, enter your title for the new challenge.
- 5.In the Slug field, enter your slug.
- 6.In the Editor tab, enter your assignment text in Markdown. For example:Step 1======Click "Explorer" > "NPM Scripts" to open the corresponding panel.Run the "test" task from it.The tests should run, and you should see the failing one in the terminal panel.Step 2======Update the function in src/sum.ts to correctly return the sum.At this point, you might want to re-run the tests to see whether the fix is helping.Check=====To complete this track, press **Check**. It will run the tests and pass if all the tests are passing.Besides regular Markdown, Instruqt supports expandable sections inside the assignment text. You create an expandable section by:
- 1.Entering a section title:
Step 1
- 2.Entering a string of = signs beneath the title:
=====
- 3.Entering the section text:
Click "Explorer" > "NPM Scripts" to...
- 7.In the Teaser field, enter your teaser for the new challenge.
- 8.Click Save to add the new challenge. ↳ Instruqt shows the Track overview page again.
- 9.Click Edit on the challenge you just added.
- 10.Click Notes, followed by New note to add a note that Instruqt shows to the learner before the challenge starts.
- 11.In the Editor tab, enter your note.
- 12.Notice the Markdown Cheat Sheet link for help on Markdown.
- 13.Click Save.
- 14.Click Tabs, followed by New tab to add a terminal to the challenge that the learner can work with.
- 15.In the Title field, enter
Shell
or any title you like. - 16.In the Type list, select Terminal.
- 17.Click Save.
- 18.Click Back. ↳ Instruqt shows the Track overview page again and your challenge is ready to be played and tested.
- 1.Activate your track directory:cd DIRECTORY_NAME⇨ Replace
DIRECTORY_NAME
with your track directory. - 2.Add a challenge to the trackinstruqt challenge create --title "CHALLENGE_TITLE"⇨ Replace
CHALLENGE_TITLE
with your title. ↳ Instruqt CLI creates a new subdirectory for the added challenge. The subdirectory's name is derived from the challenge title. For example, if the title is "How to create a Docker container", the subdirectory's name will bexx-how-to-create-a-docker-container
. Wherexx
is the sequence number of the challenge within the track. Inside the subdirectory, you will find these configuration files:├── assignment.md├── check-container├── cleanup-container├── setup-container└── solve-containerassignment.md
contains the challenge properties, notes, and the assignment text. The other files are script files that run at specific moments in the lifecycle of a challenge.
The added challenge only has a skeleton so far. To finish the challenge, you can set the challenge properties and enter the assignment text in the file
assignment.md
. This file contains a section with challenge properties and a section with the assignment text:# Challenge properties (YAML)
---
slug: how-to-create-a-docker-container
id: zedez3ar9msm
type: challenge
title: How to create a Docker container
teaser: A short description of the challenge.
notes:
- type: text
contents: |-
Replace this text with your own text
which can span multiple lines by adding "|-"
in front of your text.
tabs:
- title: Shell
type: terminal
hostname: docker-vm
difficulty: basic
timelimit: 600
---
# Assignment text (Markdown)
Multi-line note
Precede the text of your note in the
contents
property with |-
for adding a multi-line text.Take the following steps to change the challenge properties:
- 1.Open the file
assignment.md
in your editor. - 2.Change the properties of your liking.For example:
- Change property
teaser
to "Learn how to create a Docker container" - Change property
tabs: title
to "Terminal" - Change property
notes: contents
to:# Learn about DockerIn this challenge, you'll create a container.Please wait while we boot a virtual machine for you.
- 3.Save the file
assignment.md
- 4.Go to Instruqt CLI and deploy the updated track:instruqt track push
- 1.Open the file
assignment.md
in your editor. - 2.Enter your assignment text in Markdown in the
Assingment text section
.For example:🧪 Creating a Docker container=======================Use this command to build a Docker container:```docker build -t my-service .```🏁 Finish=========To complete thechallenge, press **Check**." - 3.Save the file
assignment.md
- 4.Go to Instruqt CLI and deploy the updated track:instruqt track push↳ The track with the new challenge is ready to play and test now.
Delete a challenge
To delete a challenge:
- 1.
- 2.Click the track from which you want to delete a challenge.
- 3.Click Edit on the challenge that you want to delete. ↳ The Update challenge page opens.
- 4.Click Delete this challenge. ↳ A confirmation pop-up opens.
- 5.Click OK.
Last modified 24d ago