Edit a track
This guide explains how you edit a track on Instruqt. You will learn how to:
- 1.Make edits to your local files and view your changes results on Instruqt
- 2.Edit challenges and the interstitial loading screens (called Notes)
- 3.Add additional challenges to the track
You will start out small and make a few edits to the track metadata, and upload the changes to Instruqt.
- 1.Open your terminal and navigate to the directory with the track configuration files.
- 2.On your local machine, edit the
track.yml
file and change the description, title and teaser of the track. - 3.Run
instruqt track push
to upload the track to Instruqt. - 4.To open the track overview page on Instruqt, run
instruqt track open
- 5.Refer to this image to discover where you should see your changes appear:

Before you edit a challenge, you will need to understand what challenges and their accompanying notes are on Instruqt.

A track is a series of challenges
Every track is a series of challenges. Learners can move to the next challenge as soon as they solve the current challenge.

A challenge has two screens. The first screen is the Notes screen, the second screen is the Assignment screen.
- The Notes screen shows while the challenge is loading (in the case of the first challenge, the screen also shows while the sandbox is provisioning). On a Notes screen, you can present beautifully formatted text or video to your learner.
- The Assignment screen is the hands-on part of a challenge, with a two-pane layout. The left pane lets learner interact with the sandbox and the right pane shows the assignment text.
In this example, the learner interacts with the sandbox host using the web-based terminal.
After this short introduction of challenges and notes, it is time to edit the first challenge. First, you will edit the first loading screen (the one that says "Please wait while we set up the first challenge").
In order to change the first loading screen, you will need to edit the Note accompanying the first challenge.
Take a look at the directory listing of the track directory. You will find a subdirectory
01-creating-a-directory
. The file assignment.md
has the assignment text, settings, and notes that belong to the challenge. .
├── 01-creating-a-directory
│ ├── assignment.md
│ ├── check-container
│ └── solve-container
├── config.yml
└── track.yml
Open the file
01-creating-a-directory/assignment.md
in your editor. It looks like this: 
The
assignment.md
file starts with the challenge settings preamble. The settings between the ---
lines are YAML formatted. You will get to the settings part in more detail later. For now, your task is to change the notes:- 1.Change the
contents
field of the Note and save the file. - 2.To upload your changes, run
instruqt track push
- 3.To view your changes, run
instruqt track open
and press Start to play the track. - 4.Verify that your changes are visible in the first loading screen.
While your track is still running, you can make changes to the challenge assignment text and view the results on Instruqt, without stopping and starting the track:
- 1.Open the
assignment.md
file in your editor. - 2.Edit assignment text section and save the file.
- 3.To upload your changes, run
instruqt track push
and wait for the command to complete. - 4.In your browser, reload the page with the track (restart the track if it stopped in the meantime).
- 5.Verify that your changes are visible.
Most changes are applied to running tracks as soon as you run instruqt track push.
Some changes require you to stop and start the track, including the following:
- Adding, removing and updating sandbox hosts
- Updates to setup scripts
Great tracks have more than one challenge with a focused assignment. It's time to add a second challenge to your track:
- 1.Open your terminal in the directory with the track configuration files
- 2.To add a new directory with a challenge configuration, run:
instruqt challenge create --title "Second challenge"
- 3.Verify that the command created a new directory
02-second-challenge
with the challenge configuration. - 4.Push the track with your new challenge to Instruqt with
instruqt track push
- 5.In your browser, solve the first challenge to get to the new challenge (you might have to start the track again).
That's it! You now know how to edit a track, push the changes to Instruqt and view your changes. You've also learned about the interstitial loading screens in-between challenges. We call them Notes and they show before the hands-on part of a challenge.
Last modified 11mo ago