Adding your first chapter

In the previous section you made the first changes to the lab, in this section you will start adding instructions to the lab. Instructions are what guide the end-user through the lab.

Instructions consist of chapters and pages that the end-user goes through to complete the lab. This outline of chapters and pages is defined on the lab resource, which makes it easy to move pages and chapters around by changing their order.

Creating the outline of your lab

Lets start by adding the content block to the lab resource. This block holds the outline of the lab and will dictate the structure of the instructions.

resource "lab" "main" {
  title = ...
  description = ...

  layout "single_column" {
    ...
  }

  # The newly added content block
  content {
    # The content block will contain our chapters
  }
}

Inside of the content block, you can add a chapter block for each chapter that your instructions contain. The order the chapter blocks are defined in, directly determines the order the chapters are displayed in within the instructions and how progression is determined within the lab. Each chapter has a label that defines the slug of the chapter, used when navigating between chapters.

Define a new chapter in the content block and name the slug "introduction", and set the title to "Introduction".

resource "lab" "main" {
  ...

  content {
    chapter "introduction" {
      title = "Introduction"
    } 
  }
}

Adding a page to your lab

Each chapter can contain any number of pages. These are defined by adding a page block to the chapter block you want to nest the page under. The page block also has a slug label, just like the chapter, used when navigating between pages.

Define a new page in the "introduction" chapter and name the slug first_page.

resource "lab" "main" {
  ...

  content {
    chapter "introduction" {
      title = ...

      page "first_page" {
        # The page configuration will be here
      }
    } 
  }
}

Create a page resource

The page block only defines the page inside the outline of the instructions. To configure the actual contents of the page, we need to create a page resource that can be referenced inside of the page block. This makes it possible to reuse pages between labs, when bundling them into reusable "modules".

At a minimum, a page resource needs a file field that specifies where to find the markdown file that contains the contents of the page. The path specified in the file field is either an absolute path, or relative to the file the page resource itself is defined in.

Create a new file in the root of the lab directory and name it pages.hcl. Inside of the pages.hcl file, define a page resource and give it a name of "first". Because the instructions directory is located next to the pages.hcl file the page is defined in, we can use a relative path in the file field e.g. instructions/first.md.

resource "page" "first" {
  file = "instructions/first.md"
}

Adding markdown content

Now that we have defined the page resource, we need to create the markdown file "instructions/first.md" that will contain the actual contents of the page. Create a new file in the "instructions" directory and name it the same as defined on the page resource e.g. first.md, and add markdown content to the file.

# First Page

Welcome to the first page of the introduction chapter.

The markdown file supports all standard markdown formatting, as well as custom Instruqt interactive components and templated values using the Handlebars template syntax. And variables to replace in the content can be passed to the markdown by specifying a variables map on the page resource.

If the markdown content of the page contains an H1 heading (e.g. # Heading) at the top of the file, this will be used as the fallback value for the title of the page. This value can be overridden with the title field of the page block on the lab.

Now that you have defined the page resource, we can reference it in the reference field of the page block. Update the page block on the chapter and add the reference field to it. A reference to the page resource, resource.page.first, works in the same way as you defined the reference to the layout resource in the previous section of this guide.

resource "lab" "main" {
  ...

  content {
    chapter "introduction" {
      title = "Introduction"

      page "first_page" {
        reference = resource.page.first
      }
    } 
  }
}

Displaying your instructions in the lab

The instructions are now configured on the lab, but they are not visible yet to the end user. To display the instructions, you need to assign the instructions tab to a panel on a layout of the lab. Since the layout currently has a single panel defined, lets add the instructions to that panel by adding an instructions block to the "single_column" layout block of the lab resource. Inside the instructions block, we need to assign it to a panel inside of the layout resource, by setting the panel field to the id of the panel (column/row) we want to add the instructions e.g. to "instructions" column in this case.

resource "lab" "main" {
  title = ...
  description = ...

  layout "single_column" {
    reference = resource.layout.single_panel
    
    instructions {
      panel = "instructions"
    }
  }

  content {
    ...
  }
}

Committing and pushing the changes

Like in the previous section, you can validate your changes using instruqt lab validate, and then git add, git commit, and git push the changes to GitHub. You can then go to the "Labs" section, verify the latest commit on GitHub matches the status of your lab, and start the lab.

Your lab should now have an "Instructions" tab that displays the first page that you created in this guide. When you click the "Progress" button in the top-right of the Lab UI, you should see the outline you defined on the lab resource.

Once you are done exploring your lab, click the "Stop" button at the top right of the Lab UI to shut down your lab environment and go back to the "Labs" list.