Edit a track

This guide explains how you edit a track on Instruqt. You will learn how to:
  1. 1.
    Make edits to your local files and view your changes results on Instruqt
  2. 2.
    Edit challenges and the interstitial loading screens (called Notes)
  3. 3.
    Add additional challenges to the track

Edit the track title and description

You will start out small and make a few edits to the track metadata, and upload the changes to Instruqt.
  1. 1.
    Open your terminal and navigate to the directory with the track configuration files.
  2. 2.
    On your local machine, edit the track.yml file and change the description, title and teaser of the track.
  3. 3.
    Run instruqt track push to upload the track to Instruqt.
  4. 4.
    To open the track overview page on Instruqt, run instruqt track open
  5. 5.
    Refer to this image to discover where you should see your changes appear:

Challenges and their notes

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.

Update the first loading screen

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.

A challenge and its notes are defined in one file

Take a look at the directory listing of the track directory. You will find a subdirectory 01-creating-a-directory. The file has the assignment text, settings, and notes that belong to the challenge.
├── 01-creating-a-directory
│   ├──
│   ├── check-container
│   └── solve-container
├── config.yml
└── track.yml
Open the file 01-creating-a-directory/ in your editor. It looks like this:
The 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. 1.
    Change the contents field of the Note and save the file.
  2. 2.
    To upload your changes, run instruqt track push
  3. 3.
    To view your changes, run instruqt track open and press Start to play the track.
  4. 4.
    Verify that your changes are visible in the first loading screen.
You can add more than one Note screen per challenge and use GitHub Flavored Markdown.

Change the assignment text of the first challenge

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. 1.
    Open the file in your editor.
  2. 2.
    Edit assignment text section and save the file.
  3. 3.
    To upload your changes, run instruqt track push and wait for the command to complete.
  4. 4.
    In your browser, reload the page with the track (restart the track if it stopped in the meantime).
  5. 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

Add another challenge

Great tracks have more than one challenge with a focused assignment. It's time to add a second challenge to your track:
  1. 1.
    Open your terminal in the directory with the track configuration files
  2. 2.
    To add a new directory with a challenge configuration, run: instruqt challenge create --title "Second challenge"
  3. 3.
    Verify that the command created a new directory 02-second-challenge with the challenge configuration.
  4. 4.
    Push the track with your new challenge to Instruqt with instruqt track push
  5. 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.