Assembling Courses from Modules

intermediate 12 minutes

authoring courses content-organization

Once you've created individual learning modules, the next step is assembling them into structured courses that provide a complete learning experience.

Understanding Course Structure

Courses are defined as JSON files in the content/courses/ directory. Each course:

Contains an ordered list of module slugs
Has its own metadata and summary
Can include content blocks for introductions and context
Automatically calculates total estimated time from modules

Course File Location

content/courses/
├── course-slug.json
├── another-course.json
└── getting-started.json

Course JSON Schema

A complete course JSON file contains these fields:

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

Required Course Fields

slug

The unique identifier for your course (URL-friendly):

"slug": "kubernetes-fundamentals"

Requirements:

Lowercase letters and hyphens only
Must be unique across all courses
Used in URLs: /course/kubernetes-fundamentals

title

The display name shown in the UI:

"title": "Kubernetes Fundamentals"

Best Practices:

Use title case
Keep under 60 characters
Be descriptive and specific

summary_markdown

Course overview in markdown format:

"summary_markdown": "This course introduces you to Kubernetes, the industry-standard container orchestration platform.\n\nYou'll learn to:\n- Deploy containerized applications\n- Manage resources and scaling\n- Configure networking and storage"

Tips:

Use markdown formatting (bullets, bold, etc.)
Explain what learners will achieve
Keep it concise (2-4 paragraphs)
Highlight key takeaways

modules

Ordered array of module slugs:

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

Important:

Order matters - modules appear in this sequence
Slugs must match existing module directory names
Sync script validates that modules exist
Course duration is computed from module times

Optional Course Fields

meta_description

SEO description (if different from summary):

"meta_description": "Learn Kubernetes fundamentals through hands-on labs covering pods, services, deployments, and more."

If omitted, the first 160 characters of summary_markdown are used.

badge_image_url

Completion badge or course icon:

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

Use for gamification or visual identification.

display_order

Controls sort order in course listings:

"display_order": 1

Lower numbers appear first (default: 999).

social_image

Social preview image URL:

"social_image": "https://example.com/previews/k8s-course.png"

Recommended size: 1200x630px

Content Blocks

Content blocks add rich content sections to your course detail page beyond the module list.

Content Block Types

1. Text Block General content with markdown formatting:

{
  "id": "intro",
  "type": "text",
  "title": "Welcome to the Course",
  "body_markdown": "This course covers **essential Kubernetes concepts**.\n\nYou'll gain hands-on experience with:\n- Container orchestration\n- Application deployment"
}

2. Callout Block Highlighted information box:

{
  "id": "prerequisites",
  "type": "callout",
  "title": "Prerequisites",
  "body_markdown": "Before starting this course:\n\n- Complete the Docker Basics course\n- Have access to a Kubernetes cluster\n- Install kubectl CLI"
}

3. Module Reference Embedded module card:

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

This renders as an interactive module card with metadata.

Complete Content Blocks Example

"content_blocks": [
  {
    "id": "welcome",
    "type": "text",
    "title": "Course Overview",
    "body_markdown": "Welcome to Kubernetes Fundamentals! This course takes you from zero to deploying production applications."
  },
  {
    "id": "prereqs",
    "type": "callout",
    "title": "Before You Begin",
    "body_markdown": "Ensure you have:\n- Docker basics knowledge\n- A Kubernetes cluster (minikube works)\n- 3-4 hours to complete"
  },
  {
    "id": "first-module",
    "type": "module_ref",
    "module_slug": "intro-to-kubernetes"
  }
]

Course Assembly Workflow

Step 1: Plan Your Course

Before creating the JSON file:

Define learning objectives - What will students achieve?
Identify prerequisite knowledge - What should they know first?
Select modules - Which modules belong in this course?
Determine sequencing - What order makes pedagogical sense?
Estimate total time - Will be auto-calculated from modules

Step 2: Create the JSON File

Create a new file in content/courses/:

# File: content/courses/kubernetes-fundamentals.json

Use your text editor or IDE to create the JSON structure.

Step 3: Write the Summary

Craft a compelling summary that:

Explains the course purpose
Lists key learning outcomes
Mentions prerequisites if any
Sets expectations for time and difficulty

Step 4: Add Content Blocks

Enhance the course page with:

Welcome message
Prerequisites callout
Learning objectives
Additional context or resources

Step 5: Set Metadata

Configure:

Display order (for course listing)
Tags (for filtering and discovery)
Social preview image (for sharing)
Badge image (for completion)

Step 6: Sync to HubDB

Run the courses sync command:

npm run sync:courses

The script will:

Validate your JSON
Compute total estimated_minutes
Convert markdown to HTML
Upsert to HubDB
Publish the table

Complete Course Example

{
  "slug": "kubernetes-fundamentals",
  "title": "Kubernetes Fundamentals",
  "meta_description": "Master Kubernetes basics through hands-on labs covering pods, services, deployments, storage, and networking.",
  "summary_markdown": "Learn the essential concepts and skills needed to deploy and manage applications on Kubernetes.\n\n**What You'll Learn:**\n- Core Kubernetes architecture and components\n- Deploying applications with pods and deployments\n- Exposing services and configuring networking\n- Managing persistent storage\n- Scaling and updating applications\n\nThis course provides hands-on experience through practical labs and real-world scenarios.",
  "modules": [
    "intro-to-kubernetes",
    "kubernetes-pods-and-deployments",
    "kubernetes-services",
    "kubernetes-storage",
    "kubernetes-scaling-and-updates"
  ],
  "badge_image_url": "https://example.com/badges/k8s-fundamentals.png",
  "display_order": 1,
  "tags": "kubernetes,containers,beginner,orchestration",
  "social_image": "https://example.com/social/k8s-fundamentals.png",
  "content_blocks": [
    {
      "id": "intro",
      "type": "text",
      "title": "Welcome to Kubernetes Fundamentals",
      "body_markdown": "This course is designed for developers and operators who want to learn Kubernetes from scratch. No prior Kubernetes experience required!"
    },
    {
      "id": "prereqs",
      "type": "callout",
      "title": "Prerequisites",
      "body_markdown": "**Required:**\n- Basic command line experience\n- Understanding of containers and Docker\n- Access to a Kubernetes cluster\n\n**Helpful but not required:**\n- Linux/Unix system administration\n- Networking basics"
    }
  ]
}

Module Sequencing Best Practices

Order modules to create a logical learning progression:

Foundation First - Start with core concepts
Build Incrementally - Each module builds on previous knowledge
Practical Early - Get hands-on quickly
Complexity Gradual - Increase difficulty progressively
Capstone Optional - End with a comprehensive project

Example Sequence

"modules": [
  "intro-to-kubernetes",           // 1. Overview and architecture
  "kubernetes-setup",              // 2. Getting started
  "kubernetes-pods",               // 3. Basic resource
  "kubernetes-deployments",        // 4. Production workloads
  "kubernetes-services",           // 5. Networking
  "kubernetes-configmaps-secrets", // 6. Configuration
  "kubernetes-storage",            // 7. Persistence
  "kubernetes-project"             // 8. Capstone
]

Validation and Testing

After creating your course, verify:

All module slugs exist in content/modules/
JSON is valid (use a JSON validator)
Summary markdown renders correctly
Content blocks display properly
Tags are consistent and relevant
Display order makes sense

Testing Commands

# Dry-run to see what would be synced
npm run sync:courses -- --dry-run

# Actual sync
npm run sync:courses

Common Course Assembly Patterns

Pattern 1: Linear Course

Modules follow a strict sequence, each building on the last.

Pattern 2: Hub-and-Spoke

Start with an intro, then several independent modules, end with integration.

Pattern 3: Choose-Your-Path

Modules can be completed in flexible order (use content blocks to explain).

Pattern 4: Skill-Based

Group by skill rather than chronology (e.g., all networking, then all storage).

Next Steps

With courses assembled, you're ready to:

Create pathways from multiple courses
Implement QA and troubleshooting processes
Publish and share your content