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. 1.
    Open your browser and go to ↳ Instruqt shows your content.
  2. 2.
    Click the TRACK_NAME of the track you want to add a challenge to. ↳ Instruqt shows the corresponding Track overview page.
  3. 3.
    Click Add challenge.
  4. 4.
    In the Title field, enter your title for the new challenge.
  5. 5.
    In the Slug field, enter your slug.
  6. 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.
    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. 1.
      Entering a section title: Step 1
    2. 2.
      Entering a string of = signs beneath the title: =====
    3. 3.
      Entering the section text: Click "Explorer" > "NPM Scripts" to...
  7. 7.
    In the Teaser field, enter your teaser for the new challenge.
  8. 8.
    Click Save to add the new challenge. ↳ Instruqt shows the Track overview page again.
  9. 9.
    Click Edit on the challenge you just added.
  10. 10.
    Click Notes, followed by New note to add a note that Instruqt shows to the learner before the challenge starts.
  11. 11.
    In the Editor tab, enter your note.
  12. 12.
    Notice the Markdown Cheat Sheet link for help on Markdown.
  13. 13.
    Click Save.
  14. 14.
    Click Tabs, followed by New tab to add a terminal to the challenge that the learner can work with.
  15. 15.
    In the Title field, enter Shell or any title you like.
  16. 16.
    In the Type list, select Terminal.
  17. 17.
    Click Save.
  18. 18.
    Click Back. ↳ Instruqt shows the Track overview page again and your challenge is ready to be played and tested.
  1. 1.
    Activate your track directory:
    ⇨ Replace DIRECTORY_NAME with your track directory.
  2. 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:
    ├── check-container
    ├── cleanup-container
    ├── setup-container
    └── solve-container 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 . 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.
- type: text
contents: |-
Replace this text with your own text
which can span multiple lines by adding "|-"
in front of your text.
- 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. 1.
    Open the file in your editor.
  2. 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. 3.
    Save the file
  4. 4.
    Go to Instruqt CLI and deploy the updated track:
    instruqt track push

Add the assignment text to the challenge

  1. 1.
    Open the file in your editor.
  2. 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. 3.
    Save the file
  4. 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. 1.
    Open your browser and go to ↳ Instruqt shows your My content page.
  2. 2.
    Click the track from which you want to delete a challenge.
  3. 3.
    Click Edit on the challenge that you want to delete. ↳ The Update challenge page opens.
  4. 4.
    Click Delete this challenge. ↳ A confirmation pop-up opens.
  5. 5.
    Click OK.
Nice work! Play your track to see if everything works the way you want.