Page

The page resource represents a markdown file that displays instructional content to participants. Pages contain the actual content that users read during the lab, with support for variable substitution and embedded interactive activities.

HCL Syntax

Basic Syntax

resource "page" "name" {
  title = "Getting Started"
  file  = "instructions/chapter1/intro.md"
}

Full Syntax

resource "page" "name" {
  title = "Getting Started"
  file  = "instructions/chapter1/intro.md"

  variables = {
    version     = "v1.2.3"
    api_url     = "https://api.example.com"
    region_name = "us-west-2"
  }

  activities = {
    setup_task   = resource.task.environment_setup
    knowledge_check = resource.quiz.concepts_quiz
    final_task   = resource.task.deployment
  }
}

Fields

Field	Required	Type	Description
title	✓	string	The title of the page
file	✓	string	Path to markdown file containing page content
variables		map(string)	Variables for Handlebars template substitution. Defaults to {}
activities		map(reference)	Interactive activities embedded in the page. Defaults to {}

Computed Attributes

These attributes are set by the system after the page is processed:

Field	Required	Type	Description
content		string	Processed content of the markdown file with variables and activities resolved

Variable Substitution

Pages support Handlebars template syntax for variable substitution:

## Welcome to {{service_name}}

Connect to the API at {{api_url}} using version {{version}}.

Available Helpers

Helper		Description	Example
quote		Wraps value in quotes	{{quote api_key}} → "abc123"
trim		Removes whitespace	{{trim description}}

Interactive Activities

Pages can embed interactive elements using the activities map. Activities are referenced by ID in markdown and must be defined in the page configuration.

Supported Activity Types

Activity Type		Reference	Description
task		Task	Interactive challenges with validation
quiz		Quiz	Knowledge assessments

Configuration Example

resource "page" "tutorial" {
  file = "instructions/tutorial.md"

  activities = {
    setup = resource.task.environment_setup
    quiz  = resource.quiz.knowledge_check
  }
}

Markdown Integration

Reference activities in your markdown using the activity ID:

## Setup Your Environment

<instruqt-task id="setup"></instruqt-task>

## Test Your Knowledge

<instruqt-quiz id="quiz"></instruqt-quiz>

Activity Tags

Tag	Required Content	Purpose
<instruqt-task>	Self-closing tag (no content)	Embeds an interactive task
<instruqt-quiz>	Self-closing tag (no content)	Embeds a knowledge quiz

Validation Rules

• File paths: Must exist and be relative to the config file location
• Activity references: All activities used in markdown must be defined in the activities map
• Activity IDs: Must be unique within the page and follow identifier rules (alphanumeric and underscore only, cannot start with a number)
• Activity types: Only task and quiz resources can be used as activities
• Variable names: Must be valid identifiers (alphanumeric and underscore only, cannot start with a number)
• Variable values: Must be strings and cannot contain unescaped Handlebars delimiters
• Markdown syntax: Activity tags must be properly closed and cannot be nested

Examples

Basic Page

resource "page" "welcome" {
  title = "Welcome to Docker"
  file  = "instructions/intro/welcome.md"
}

Page with Variables

resource "page" "configuration" {
  title = "API Configuration"
  file  = "instructions/reference/config.md"

  variables = {
    api_version = "v2"
    endpoint    = "https://api.example.com"
    timeout     = "30s"
  }
}

Page with Activities

resource "page" "hands_on" {
  title = "Hands-On Practice"
  file  = "instructions/practice/exercises.md"

  activities = {
    docker_setup    = resource.task.install_docker
    container_task  = resource.task.run_container
    knowledge_quiz  = resource.quiz.docker_concepts
  }
}

Complex Page Example

resource "page" "advanced_tutorial" {
  title = "Advanced Container Management"
  file  = "instructions/advanced/tutorial.md"

  variables = {
    registry_url = "registry.example.com"
    namespace    = "production"
    image_tag    = "v1.0.0"
  }

  activities = {
    build_image     = resource.task.build_custom_image
    deploy_app      = resource.task.deploy_application
    scaling_quiz    = resource.quiz.scaling_concepts
    cleanup_task    = resource.task.cleanup_resources
  }
}

Best Practices

1. Descriptive Titles: Use clear, descriptive titles that help participants understand the page content
2. Organized File Structure: Store markdown files in logical directory structures (e.g., instructions/chapter_name/page_name.md)
3. Variable Naming: Use clear, consistent variable names that are easy to understand in templates
4. Activity Flow: Order activities logically within the page content to guide participant progression
5. Content Length: Keep pages focused on specific topics - break long content into multiple pages
6. Template Testing: Test variable substitution with different values to ensure templates work correctly