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. 
Challenge definition
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 choose Text , you can enter your content in Markdown. If you choose Image or Video, 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.
Before you begin
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.
Add a challenge
Pick the Web UI or the Instruqt CLI route depending on your preference:
🌐 Web UI
💻 Instruqt CLI
1.Open your browser and go to play.instruqt.com.
↳ Instruqt shows your content.  
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 track
instruqt 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 be xx-how-to-create-a-docker-container . Where xx 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-container
assignment.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.

Finish the 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.
​
Change challenge properties
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 Docker
    
 In this challenge, you'll create a container. 
 Please wait while we boot a virtual machine for you.
​
See the Challenges topic details about challenge properties.
​
3.Save the file assignment.md 
4.Go to Instruqt CLI and deploy the updated track:
instruqt track push
​
Add the assignment text to the challenge
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 the
challenge, 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.Open your browser and go to play.instruqt.com.
↳ Instruqt shows your My content page.  
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.
Nice work! Play your track to see if everything works the way you want.
Build challenges
Add a script to check challenge execution
Last modified 24d ago
Add a challenge to a track

Challenge definition

Before you begin

Add a challenge

Finish the challenge

​

Change challenge properties

Add the assignment text to the challenge
