Digital course creation guide

e. The solution involves schema definition, content authoring in Markdown/MDX, and a build pipeline that transforms source assets into distributable formats.

1. Schema Design

Define a robust TypeScript interface to enforce structure. This schema acts as the contract between content authors and the delivery engine.

// schema/course.types.ts

export interface Course {
  id: string;
  slug: string;
  title: string;
  description: string;
  version: string;
  metadata: CourseMetadata;
  modules: Module[];
}

export interface CourseMetadata {
  author: string;
  tags: string[];
  difficulty: 'beginner' | 'intermediate' | 'advanced';
  estimatedDuration: number; // minutes
  prerequisites: string[];
}

export interface Module {
  id: string;
  title: string;
  lessons: Lesson[];
}

export interface Lesson {
  id: string;
  title: string;
  type: 'theory' | 'lab' | 'quiz' | 'project';
  content: string; // MDX string
  assets: Asset[];
  duration: number; // minutes
}

export interface Asset {
  id: string;
  type: 'video' | 'image' | 'code' | 'diagram';
  src: string;
  alt: string;
  metadata?: Record<string, unknown>;
}

2. Content Authoring with MDX

MDX (Markdown + JSX) allows embedding interactive components directly within content. This enables code blocks, quizzes, and warnings to be treated as first-class citizens.

// content/lessons/intro-to-react.mdx
---
title: "Introduction to React Components"
duration: 15
type: theory
tags: ["react", "components", "jsx"]
---

import { CodeBlock } from '@/components/CodeBlock';
import { Quiz } from '@/components/Quiz';
import { Warning } from '@/components/Warning';

React components are the building blocks of any React application. 
They allow you to split the UI into independent, reusable pieces.

## Functional Components

Modern React uses functional components. Here is a basic example:

<CodeBlock language="tsx" title="Greeting.tsx">
{`export function Greeting({ name }: { name: string }) {
  return <h1>Hello, {name}!</h1>;
}`}
</CodeBlock>

<Warning title="Best Practice">
Always use functional components with hooks instead of class components 
for new development.
</Warning>

## Quiz: Component Basics

<Quiz 
  id="quiz-intro-1"
  question="Which of the following is a valid React component?"
  options={[
    { text: "function MyComp() {}", correct: true },
    { text: "const MyComp = () => {}", correct: true },
    { text: "class MyComp extends Component", correct: false }
  ]}
/>

3. Build Pipeline Architecture

The build process parses MDX files, validates against the schema, extracts assets, and generates outputs.

// scripts/build-course.ts
import { compileMDX } from 'next-mdx-remote/rsc';
import { z } from 'zod';
import { courseSchema } from './schema/course.schema';
import fs from 'fs/promises';
import path from 'path';

async function buildCourse(sourceDir: string, outputDir: string) {
  // 1. Read and parse source files
  const files = await fs.readdir(sourceDir);
  const lessons = await Promise.all(
    files
      .filter(f => f.endsWith('.mdx'))
      .map(async (file) => {
        const content = await fs.readFile(path.join(sourceDir, file), 'utf-8');
        const { frontmatter, content: mdxContent } = await compileMDX({
          source: content,
          components: { CodeBlock, Quiz, Warning },
          parseFrontmatter: true,
        });
        
        // 2. Validate against schema
        const validatedLesson = lessonSchema.parse({
          id: path.parse(file).name,
          ...frontmatter,
          content: mdxContent,
        });
        
        return validatedLesson;
      })
  );

  // 3. Generate structured course object
  const course: Course = {
    id: 'ts-react-basics',
    slug: 'ts-react-basics',
    title: 'TypeScript React Basics',
    description: '...',
    version: '1.0.0',
    metadata: {
      author: 'DevTeam',
      tags: ['typescript', 'react'],
      difficulty: 'beginner',
      estimatedDuration: lessons.reduce((acc, l) => acc + l.duration, 0),
      prerequisites: ['javascript'],
    },
    modules: [{
      id: 'mod-1',
      title: 'Fundamentals',
      lessons: lessons,
    }],
  };

  // 4. Export to multiple formats
  await fs.mkdir(outputDir, { recursive: true });
  
  // JSON for API/LMS
  await fs.writeFile(
    path.join(outputDir, 'course.json'),
    JSON.stringify(course, null, 2)
  );

  // Static HTML for web distribution
  await generateStaticSite(course, path.join(outputDir, 'web'));
  
  console.log(`✅ Course built: ${lessons.length} lessons, ${course.metadata.estimatedDuration}m duration.`);
}

4. Architecture Decisions

• File-Based vs. Headless CMS: For technical courses, file-based storage (Git) is superior. It provides native version control, diffing, and branching capabilities essential for tracking content changes alongside code updates.
• MDX over Pure Markdown: MDX is mandatory for technical content. It allows the injection of dynamic components like live code editors, interactive diagrams, and assessment widgets, transforming passive reading into active learning.
• Schema Validation: Using Zod or TypeScript interfaces ensures content integrity. Broken links, missing metadata, or malformed code blocks are caught at build time, preventing runtime errors in the delivery platform.
• Asset Isolation: Media assets should be stored separately from text content, referenced by ID. This allows the build pipeline to optimize images, generate thumbnails, and ensure CDN caching without touching the content files.

Pitfall Guide

1. Over-Engineering the Schema:

   • Mistake: Creating a schema with excessive nesting or granular fields that burden authors.
   • Correction: Start with a minimal viable schema. Add fields only when data requirements dictate. Use optional fields for metadata that isn't critical for rendering.

2. Ignoring WCAG Accessibility Standards:

   • Mistake: Treating accessibility as an afterthought.
   • Correction: Enforce alt text on all assets via schema validation. Ensure MDX components render semantic HTML. Integrate automated accessibility linting into the build pipeline.

3. Mixing Media and Text Without Structure:

   • Mistake: Embedding raw HTML or unstructured asset paths in content.
   • Correction: Use components for all assets. A video should be <Video src="..." caption="..." />, not a raw <iframe>. This enables consistent styling, lazy loading, and analytics tracking.

4. No Versioning Strategy for Content:

   • Mistake: Updating content without versioning, breaking integrations or user bookmarks.
   • Correction: Implement semantic versioning for courses. Store historical versions in Git. Use the version field in the schema to manage API responses and feature flags.

5. Platform Lock-in via Proprietary Formats:

   • Mistake: Using platform-specific shortcodes that cannot be exported.
   • Correction: Stick to standard MDX and JSON. If platform-specific features are needed, abstract them behind components that can be swapped out during export.

6. Neglecting Interactivity in Code Courses:

   • Mistake: Displaying code blocks without execution context.
   • Correction: Integrate sandboxed code execution environments. Use components like <CodeSandbox> that allow learners to run and modify code directly within the lesson.

7. Performance Bottlenecks with Heavy Assets:

   • Mistake: Serving large videos or uncompressed images directly from the origin.
   • Correction: Implement a CDN strategy. Use adaptive bitrate streaming for video. Lazy-load all media assets. Generate WebP/AVIF images automatically during the build process.

Production Bundle

Action Checklist

• Define Schema: Create TypeScript interfaces and Zod schemas for Course, Module, Lesson, and Asset.
• Initialize Repository: Set up a Git repository with a structured directory layout (content/, assets/, components/).
• Configure MDX Pipeline: Install next-mdx-remote or equivalent; configure custom components for code, quizzes, and warnings.
• Implement Build Script: Write a script to parse MDX, validate schema, and export JSON/HTML outputs.
• Set Up Asset Pipeline: Configure image optimization and video transcoding workflows.
• Add Validation Hooks: Integrate pre-commit hooks to check for broken links and missing metadata.
• Create Distribution Targets: Define export formats (Web, LMS API, PDF, EPUB).
• Implement Analytics: Add tracking hooks to component interactions and lesson completion events.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Solo Technical Creator	Static Site + Git	Low overhead, full control, free hosting options.	Low (Time investment only)
Enterprise Training Portal	Headless CMS + API	Centralized management, role-based access, integration with HR systems.	Medium (Infrastructure + Tooling)
Interactive Coding Bootcamp	MDX + Sandboxed Runtime	Requires live code execution, immediate feedback, and complex component logic.	High (Compute resources + Dev time)
Multi-Format Publishing	Structured Source + Build Pipeline	Single source of truth generates Web, PDF, and LMS outputs automatically.	Medium (Build complexity)

Configuration Template

Copy this template to initialize your course structure.

// config/course.config.ts
import { defineConfig } from '@codcompass/course-sdk';

export default defineConfig({
  course: {
    id: 'my-technical-course',
    title: 'Advanced System Design',
    version: '1.0.0',
    author: 'Engineering Team',
  },
  build: {
    output: {
      formats: ['json', 'html', 'pdf'],
      assets: {
        optimize: true,
        cdn: 'https://cdn.example.com/assets',
      },
    },
    components: {
      code: {
        sandbox: true,
        theme: 'github-dark',
      },
      video: {
        provider: 'custom',
        lazyLoad: true,
      },
    },
  },
  validation: {
    strict: true,
    checkAccessibility: true,
    checkBrokenLinks: true,
  },
  lms: {
    integration: 'xapi',
    tracking: {
      enabled: true,
      events: ['lesson_start', 'lesson_complete', 'quiz_pass'],
    },
  },
});

Quick Start Guide

1. Initialize Project: Run npx @codcompass/course-cli init my-course. This scaffolds the directory structure, installs dependencies, and generates the config template.

2. Create First Lesson: Add content/lessons/01-introduction.mdx. Use the provided frontmatter template and write content using standard Markdown with embedded components.

3. Preview Locally: Execute npm run dev. The CLI starts a local server rendering your lessons with full component support. Verify layout, code highlighting, and interactivity.

4. Validate and Build: Run npm run validate to check schema compliance and accessibility. Once passed, run npm run build to generate the production bundle in the dist/ directory.

5. Deploy: Upload the dist/ contents to your hosting provider or LMS. The JSON manifest can be ingested by your delivery API to populate the course catalog.