Skip to content

Quest Templates and Tools

This directory contains templates and tools for creating and managing quests in the IT-Journey quest system.

Templates

Main Quest Template

File: main-quest-template.md

Full template for main storyline quests. Includes: - Complete frontmatter with all required and optional fields - Quest network positioning diagrams - Multi-platform implementation paths (macOS, Windows, Linux, Cloud) - Progressive learning chapters (3+ chapters) - Hands-on mastery challenges (Novice, Intermediate, Advanced) - Rewards and achievement systems - Resource library and next steps

Use for: Core learning path quests that advance the main storyline.

Level README Template

File: level-readme-template.md

Standard template for level directory README files. Includes: - Level overview and positioning - Complete quest listings (main, side, bonus) - Quest network map with Mermaid diagrams - Character class progression paths - Prerequisites and unlocks - Resources and tools for the level

Use for: Creating or updating level directory README files.

Side Quest Template (Coming Soon)

File: side-quest-template.md (Planned)

Template for optional learning adventures that enhance skills without being required for progression.

Bonus Quest Template (Coming Soon)

File: bonus-quest-template.md (Planned)

Template for advanced challenges and mastery demonstrations.

Tools

Quest Generation Script

File: ../scripts/quest/generate-placeholder-quest.sh

Automated script to create placeholder quest files from templates.

Usage: 

./scripts/quest/generate-placeholder-quest.sh <level> <quest-slug> "<quest-title>" [options]

Examples: 

# Create a basic quest
./scripts/quest/generate-placeholder-quest.sh 0110 database-design-fundamentals "Database Design Fundamentals"

# Create with additional options
./scripts/quest/generate-placeholder-quest.sh 0110 sql-sorcery "SQL Sorcery" \
  --difficulty medium \
  --time "45-60 minutes" \
  --tech sql \
  --skill data-engineering

# Dry run to preview
./scripts/quest/generate-placeholder-quest.sh 1101 ml-fundamentals "ML Fundamentals" --dry-run

Options: - --difficulty: easy, medium, hard, epic (default: easy) - --type: main_quest, side_quest, bonus_quest (default: main_quest) - --time: Estimated time (e.g., "30-45 minutes") - --tech: Primary technology (e.g., docker, react, python) - --skill: Skill focus (e.g., frontend, backend, devops) - --dry-run: Preview without creating files

Quest Network Validator

File: ../scripts/quest/validate-quest-network.py

Python script to validate quest network integrity.

Usage: 

python3 scripts/quest/validate-quest-network.py

Checks: - ✅ Required frontmatter fields present - ✅ Quest dependencies exist - ✅ No circular dependencies - ✅ Identifies orphaned quests - ✅ Validates quest relationships - ✅ Generates a report with statistics, errors, and warnings

Output: - Quest statistics (total, complete, placeholder, draft) - List of errors (broken dependencies, missing fields) - List of warnings (orphaned quests, invalid formats) - Overall validation status (pass/fail)

Quick Start Guide

Creating a New Quest

  1. Plan your quest:
  2. Determine level (binary format: 0000-1111)
  3. Choose quest type (main, side, or bonus)
  4. Define difficulty and estimated time

  5. Identify technologies and skills covered

  6. Generate placeholder: 

    ./scripts/quest/generate-placeholder-quest.sh 0110 my-quest-slug "My Quest Title" \
  --difficulty medium --tech python --skill backend

  7. Edit the generated file:

  8. Fill in the description and learning objectives
  9. Add multi-platform implementation details
  10. Create hands-on challenges
  11. Define prerequisites and unlocks

  12. Add resources and documentation links

  13. Update level README:

  14. Add quest to appropriate section
  15. Update quest network diagram

  16. Include in character class paths

  17. Validate the quest network: 

    python3 scripts/quest/validate-quest-network.py

  18. When complete:

  19. Set draft: false in frontmatter
  20. Update home.md and main README.md
  21. Create git commit with conventional format

Creating a New Level

  1. Create level directory: 

    mkdir -p pages/_quests/XXXX  # Replace XXXX with binary level

  2. Generate level README: 

    cp pages/_quests/templates/level-readme-template.md pages/_quests/XXXX/README.md

  3. Customize level README:

  4. Fill in level details
  5. Define core objectives
  6. List planned quests

  7. Create quest network diagram

  8. Generate quests for the level: 

    ./scripts/quest/generate-placeholder-quest.sh XXXX quest-1-slug "Quest 1 Title"
./scripts/quest/generate-placeholder-quest.sh XXXX quest-2-slug "Quest 2 Title"
# ... etc

Template Customization

Frontmatter Fields

Required Fields (all quests must have): - title: Quest title - description: SEO-friendly description (150-300 chars) - level: Binary level (e.g., "0110") - difficulty: 🟢 Easy | 🟡 Medium | 🔴 Hard | ⚔️ Epic - estimated_time: Time estimate (e.g., "30-45 minutes") - quest_type: main_quest | side_quest | bonus_quest - permalink: URL path for the quest

Recommended Fields: - quest_dependencies: Prerequisites and unlocks - quest_relationships: Parent, child, parallel, sequel quests - learning_paths: Character class alignment - rewards: Badges, skills, XP - validation_criteria: Completion requirements

Optional Fields: - quest_line: Campaign/storyline name - quest_arc: Story arc grouping - quest_mapping: Position on quest map - primary_technology: Main tech focus - skill_focus: Skill category

Content Structure

Each quest should include:

  1. Epic Introduction - Fantasy-themed opening
  2. Quest Network Position - Mermaid diagram
  3. Quest Objectives - Primary, Secondary, Mastery
  4. Prerequisites - Knowledge, System, Skill Level
  5. Multi-Platform Paths - macOS, Windows, Linux, Cloud
  6. Learning Chapters (3-5):
  7. Skills to forge
  8. Step-by-step implementation
  9. Knowledge checks
  10. Quick wins and checkpoints
  11. Mastery Challenges (3):
  12. Novice (🟢)
  13. Intermediate (🟡)
  14. Advanced (🔴)
  15. Rewards & Achievements
  16. Next Steps & Quest Network
  17. Resource Library

Best Practices

Quest Design

  1. Clear Learning Objectives: Be specific and measurable
  2. Progressive Difficulty: Build from simple to complex
  3. Hands-On Practice: Include practical implementations
  4. Multi-Platform: Cover macOS, Windows, Linux, Cloud where applicable
  5. Fantasy Theme: Maintain RPG language and metaphors
  6. Validation Criteria: Define clear success metrics

Frontmatter Standards

  1. Complete Metadata: Fill all required fields
  2. Accurate Dependencies: Link to actual quest permalinks
  3. Proper Formatting: Follow YAML syntax strictly
  4. Consistent Naming: Use kebab-case for slugs
  5. Draft Status: Set draft: true until complete

Quest Network

  1. No Orphans: Every quest should be referenced
  2. Clear Progression: Define prerequisites and unlocks
  3. No Circular Deps: Avoid circular dependencies
  4. Character Alignment: Map to character classes
  5. Level Coherence: Quests should fit level theme

Validation Checklist

Before marking a quest complete:

  • All required frontmatter fields present
  • Quest network position diagram included
  • All prerequisites listed and linked
  • All unlocked quests listed and linked
  • Multi-platform instructions present
  • At least 2 hands-on challenges defined
  • Learning objectives clearly stated
  • Validation criteria specified
  • Fantasy theme integrated throughout
  • Resources section populated
  • Level README updated
  • home.md updated
  • Main README.md updated
  • All internal links validated
  • Validation script passes

Contributing

When creating new templates or improving existing ones:

  1. Follow existing template structure
  2. Comment each field and section so users know what to fill in
  3. Test with generation script
  4. Update this README
  5. Submit PR with examples

Support

  • Documentation: See .github/instructions/quest.instructions.md
  • Build Plan: See QUEST_BUILD_PLAN.md
  • Issues: Report template issues in GitHub Issues
  • Discussions: Use GitHub Discussions for questions

Last Updated: 2025-11-29 Maintainers: IT-Journey Team