Page

Defined incontent.hcl

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

Use Cases

As a lab author, you use page resources to create structured learning content:

• Step-by-Step Instructions: Provide detailed, sequential instructions that guide users through complex procedures and learning objectives
• Interactive Learning: Embed tasks, quizzes, and other activities directly within instructional content for immediate practice and assessment
• Dynamic Content: Use variable substitution to personalize content with user-specific values, environment details, or configuration parameters

Pages form the instructional backbone of your lab, providing the knowledge and guidance users need to successfully complete hands-on 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	Type	Required	Description
title	string	✓	Page title displayed in the UI
file	string	✓	Path to the markdown file containing page content ConstraintsMust be a markdown file (.md extension)
variables	map(string)	—	Variables for template interpolation in the markdown content
activities	map(reference)task, quiz	—	Activity references mapped to IDs used in markdown

Computed Attributes

These attributes are set by the system and are read-only.

Attribute	Type	Description
content	string	Processed markdown content (computed from file + variables + activities)

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

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 users 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 user 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