Pathways & Content Blocks

intermediate 12 minutes
authoring pathways content-organization advanced

Pathways are the highest level of content organization in Hedgehog Learn, combining multiple courses (or modules) into comprehensive learning journeys.

Understanding Pathways

A pathway represents a complete learning journey that:

  • Combines multiple related courses
  • Can alternatively contain a curated list of modules
  • Provides overarching context and guidance
  • Offers learners a clear progression toward mastery
  • Uses content blocks to create rich, guided experiences

Pathway vs Course vs Module

  • Module: Single learning unit (20-60 minutes)
  • Course: Collection of related modules (2-8 hours)
  • Pathway: Collection of courses or modules (days to weeks)

Pathway File Location

content/pathways/
├── pathway-slug.json
├── advanced-networking.json
└── cloud-native-expert.json

Pathway JSON Schema

A complete pathway JSON file:

{
  "slug": "pathway-slug",
  "title": "Pathway Title",
  "meta_description": "SEO description",
  "summary_markdown": "Pathway overview in markdown",
  "courses": [
    "course-slug-1",
    "course-slug-2"
  ],
  "modules": [
    "module-slug-1",
    "module-slug-2"
  ],
  "badge_image_url": "https://example.com/badge.png",
  "display_order": 1,
  "tags": "tag1,tag2,tag3",
  "social_image": "https://example.com/social.png",
  "content_blocks": []
}

Required Pathway Fields

slug

Unique identifier for the pathway:

"slug": "kubernetes-expert"

Requirements:

  • Lowercase with hyphens
  • Must be unique across all pathways
  • Used in URLs: /pathway/kubernetes-expert

title

Display name:

"title": "Kubernetes Expert Pathway"

Use descriptive, aspirational titles that convey the outcome.

summary_markdown

Overview in markdown:

"summary_markdown": "Become a Kubernetes expert through this comprehensive learning pathway.\n\n**Journey Overview:**\n- Master core concepts and operations\n- Learn advanced networking and security\n- Deploy production-grade clusters\n- Prepare for CKA/CKAD certification"

courses OR modules

Must provide at least one (can provide both):

Course-based pathway:

"courses": [
  "kubernetes-fundamentals",
  "kubernetes-networking",
  "kubernetes-security",
  "kubernetes-production"
]

Module-based pathway:

"modules": [
  "intro-to-kubernetes",
  "kubernetes-pods",
  "kubernetes-services"
]

Mixed approach (both courses and modules): Courses take precedence for duration calculations.

Optional Pathway Fields

meta_description

"meta_description": "Complete pathway to Kubernetes mastery covering fundamentals, advanced topics, and production deployment."

badge_image_url

"badge_image_url": "https://example.com/badges/k8s-expert.png"

display_order

"display_order": 1

Lower numbers appear first in pathway listings.

tags

"tags": "kubernetes,advanced,certification,expert"

social_image

"social_image": "https://example.com/social/k8s-expert.png"

Content Blocks Deep Dive

Content blocks transform a simple list into a rich learning experience.

Four Content Block Types

1. Text Block - General content

2. Callout Block - Highlighted information

3. Module Reference - Embedded module card

4. Course Reference - Embedded course card (NEW for pathways!)

1. Text Content Blocks

Use for introductions, explanations, and guidance:

{
  "id": "welcome",
  "type": "text",
  "title": "Welcome to the Pathway",
  "body_markdown": "This learning pathway will take you from Kubernetes novice to expert.\n\n**Time Commitment:** 40-60 hours\n**Prerequisites:** Basic Docker knowledge\n**Certification Prep:** Aligned with CKA exam"
}

Use text blocks for:

  • Pathway introductions
  • Learning objectives
  • Career outcomes
  • Study recommendations

2. Callout Content Blocks

Use for important notices, prerequisites, or tips:

{
  "id": "prerequisites",
  "type": "callout",
  "title": "Important Prerequisites",
  "body_markdown": "**Before starting this pathway:**\n\n✓ Complete Docker Fundamentals course\n✓ Have Linux command line experience\n✓ Access to a Kubernetes cluster (we recommend minikube for learning)\n\n*Estimated prerequisite time: 8 hours*"
}

Use callouts for:

  • Prerequisites
  • Important warnings
  • Study tips
  • Certification information
  • Time estimates

3. Module Reference Blocks

Embed specific modules directly in the pathway flow:

{
  "id": "quick-intro",
  "type": "module_ref",
  "module_slug": "intro-to-kubernetes"
}

This renders as an interactive card showing:

  • Module title
  • Description
  • Estimated time
  • Difficulty level
  • Link to module

Use module references when:

  • Including standalone modules outside courses
  • Highlighting specific optional modules
  • Creating choose-your-own-path experiences

4. Course Reference Blocks

Embed course cards in the pathway:

{
  "id": "fundamentals-course",
  "type": "course_ref",
  "course_slug": "kubernetes-fundamentals"
}

This renders a course card with:

  • Course title and summary
  • Module count
  • Total estimated time
  • Link to course

Use course references:

  • As the primary content structure
  • To show course relationships
  • For sequential learning paths

Content Block Ordering Strategy

Content blocks appear in the order listed. Design the flow strategically:

Pattern 1: Guided Pathway

"content_blocks": [
  {
    "id": "intro",
    "type": "text",
    "title": "Pathway Introduction",
    "body_markdown": "..."
  },
  {
    "id": "prereqs",
    "type": "callout",
    "title": "Prerequisites",
    "body_markdown": "..."
  },
  {
    "id": "course1",
    "type": "course_ref",
    "course_slug": "fundamentals"
  },
  {
    "id": "course2",
    "type": "course_ref",
    "course_slug": "advanced"
  },
  {
    "id": "next-steps",
    "type": "text",
    "title": "Next Steps",
    "body_markdown": "..."
  }
]

Pattern 2: Choose-Your-Path

"content_blocks": [
  {
    "id": "intro",
    "type": "text",
    "title": "Choose Your Learning Path",
    "body_markdown": "..."
  },
  {
    "id": "path-callout",
    "type": "callout",
    "title": "Three Paths Available",
    "body_markdown": "- **Developer Track**: Focus on application deployment\n- **Operations Track**: Infrastructure and clusters\n- **Security Track**: Security and compliance"
  },
  {
    "id": "dev-course",
    "type": "course_ref",
    "course_slug": "k8s-for-developers"
  },
  {
    "id": "ops-course",
    "type": "course_ref",
    "course_slug": "k8s-for-operators"
  },
  {
    "id": "sec-course",
    "type": "course_ref",
    "course_slug": "k8s-security"
  }
]

Pattern 3: Milestone-Based

"content_blocks": [
  {
    "id": "milestone1",
    "type": "text",
    "title": "Milestone 1: Foundation",
    "body_markdown": "..."
  },
  {
    "id": "course1",
    "type": "course_ref",
    "course_slug": "basics"
  },
  {
    "id": "milestone2",
    "type": "text",
    "title": "Milestone 2: Intermediate",
    "body_markdown": "..."
  },
  {
    "id": "course2",
    "type": "course_ref",
    "course_slug": "intermediate"
  }
]

Complete Pathway Example

{
  "slug": "kubernetes-expert-pathway",
  "title": "Kubernetes Expert Pathway",
  "meta_description": "Comprehensive learning pathway from Kubernetes basics to expert-level mastery, including certification preparation.",
  "summary_markdown": "Transform from Kubernetes beginner to certified expert through this structured learning pathway.\n\n**What You'll Achieve:**\n- Deploy and manage production Kubernetes clusters\n- Master advanced networking and security\n- Implement GitOps and CI/CD workflows\n- Prepare for CKA and CKAD certifications\n\n**Total Time:** 60-80 hours over 6-12 weeks",
  "courses": [
    "kubernetes-fundamentals",
    "kubernetes-advanced-networking",
    "kubernetes-security-hardening",
    "kubernetes-production-operations"
  ],
  "badge_image_url": "https://example.com/badges/k8s-expert.png",
  "display_order": 1,
  "tags": "kubernetes,expert,certification,advanced",
  "social_image": "https://example.com/social/k8s-expert-pathway.png",
  "content_blocks": [
    {
      "id": "welcome",
      "type": "text",
      "title": "Welcome to the Kubernetes Expert Pathway",
      "body_markdown": "This comprehensive pathway takes you from zero to Kubernetes expert. You'll gain hands-on experience through 15+ labs and real-world scenarios.\n\n**Pathway Duration:** 60-80 hours\n**Difficulty:** Beginner to Advanced\n**Certifications:** Prepares for CKA and CKAD exams"
    },
    {
      "id": "prerequisites",
      "type": "callout",
      "title": "Before You Begin",
      "body_markdown": "**Required:**\n- Basic Linux command line skills\n- Understanding of containers and Docker\n- Access to a computer with 8GB+ RAM\n\n**Recommended:**\n- Basic networking knowledge\n- Experience with YAML\n- Git fundamentals\n\n*Complete the Docker Fundamentals course if you're new to containers.*"
    },
    {
      "id": "phase1",
      "type": "text",
      "title": "Phase 1: Foundations (15-20 hours)",
      "body_markdown": "Start with core Kubernetes concepts, architecture, and basic operations."
    },
    {
      "id": "fundamentals",
      "type": "course_ref",
      "course_slug": "kubernetes-fundamentals"
    },
    {
      "id": "phase2",
      "type": "text",
      "title": "Phase 2: Advanced Networking (15-20 hours)",
      "body_markdown": "Deep dive into Kubernetes networking, including CNI, network policies, and service mesh."
    },
    {
      "id": "networking",
      "type": "course_ref",
      "course_slug": "kubernetes-advanced-networking"
    },
    {
      "id": "phase3",
      "type": "text",
      "title": "Phase 3: Security (15-20 hours)",
      "body_markdown": "Learn security best practices, RBAC, pod security, and compliance."
    },
    {
      "id": "security",
      "type": "course_ref",
      "course_slug": "kubernetes-security-hardening"
    },
    {
      "id": "phase4",
      "type": "text",
      "title": "Phase 4: Production Operations (15-20 hours)",
      "body_markdown": "Master production deployments, monitoring, troubleshooting, and GitOps."
    },
    {
      "id": "production",
      "type": "course_ref",
      "course_slug": "kubernetes-production-operations"
    },
    {
      "id": "certification",
      "type": "callout",
      "title": "Certification Preparation",
      "body_markdown": "This pathway aligns with:\n\n- **CKA (Certified Kubernetes Administrator)** - Covers 85% of exam topics\n- **CKAD (Certified Kubernetes Application Developer)** - Covers 75% of exam topics\n\nAfter completing this pathway, review the official exam curriculum and take practice tests."
    },
    {
      "id": "next-steps",
      "type": "text",
      "title": "Beyond This Pathway",
      "body_markdown": "After mastering this pathway, consider:\n\n- **Advanced Topics:** Service mesh (Istio/Linkerd), serverless (Knative)\n- **Specialization:** Kubernetes security expert, GitOps specialist\n- **Contribution:** Join the Kubernetes community, contribute to projects\n- **Teaching:** Share your knowledge through blog posts, talks, or courses"
    }
  ]
}

Syncing Pathways

Sync pathways to HubDB:

npm run sync:pathways

The sync script:

  • Validates pathway JSON
  • Computes module counts and estimated times
  • Converts markdown to HTML
  • Serializes content blocks as JSON
  • Upserts to HubDB
  • Publishes the table

Pathway Design Best Practices

1. Set Clear Outcomes

Start with the end goal - what will learners achieve?

2. Scaffold Learning

Structure content from simple to complex.

3. Provide Choice

Allow learners to customize their path when appropriate.

4. Set Expectations

Be transparent about time commitment and prerequisites.

5. Celebrate Milestones

Break long pathways into achievable phases.

6. Link to External Resources

Use text blocks to reference certification info, communities, etc.

Testing Your Pathway

  • All course/module slugs exist
  • JSON is valid
  • Content blocks render correctly
  • Links work
  • Markdown formatting displays properly
  • Estimated time makes sense
  • Tags are relevant

Dry-Run Testing

npm run sync:pathways -- --dry-run

Common Pathway Patterns

Linear Expert Path

Start → Intermediate → Advanced → Expert

Multi-Track Path

Shared foundation → Split by role → Converge at advanced

Certification Path

Aligned with external certification requirements

Project-Based Path

Each course ends with a cumulative project

Next Steps

Now you understand pathways! Continue to:

Resources