How to Add New Lessons to the Curriculum Structure in Web-Dev-For-Beginners

To add new lessons to the curriculum structure, create a numbered folder in the repository root, populate it with a README.md based on the lesson-template, and register the lesson in the master table within the root README.md.

The microsoft/Web-Dev-For-Beginners repository organizes its 24-lesson curriculum through a strict folder naming convention and central registry. When you add new lessons to the curriculum structure, you must follow the established numeric prefix system and template scaffolding to ensure compatibility with the automated translation pipeline and Docsify-based documentation site.

Understanding the Curriculum Architecture

The curriculum uses a hierarchical folder structure where each top-level directory represents a lesson series. These folders use numeric prefixes to enforce chronological ordering.

• Series folders: Located in the repository root, named with pattern <number>-<kebab-case-description> (e.g., 1-getting-started-lessons, 2-js-basics, 3-terrarium).
• Lesson content: Each series folder contains a README.md that holds the actual lesson material, quizzes, and assignments.
• Master registry: The root README.md contains a large markdown table (around lines 551-580) that indexes every lesson for the navigation system.

Step-by-Step Guide to Add New Lessons

1. Create the Lesson Folder

Choose the appropriate numeric prefix based on where the lesson fits in the curriculum sequence. If extending an existing series, use the next available number within that series folder. For a new series, create a new top-level folder with the next available number.

# Example: Creating a new series folder

mkdir 11-progressive-web-apps

2. Scaffold Content Using the Official Template

Copy the official lesson template into your new folder. This ensures your lesson includes the required pedagogical structure: pre-lecture quiz, introduction, step-by-step tasks, knowledge checks, challenge, and post-lecture quiz.

# From repository root

cp -r lesson-template/ 11-progressive-web-apps/your-lesson-slug/

Edit the generated README.md to replace placeholders. The template requires specific heading hierarchy to render correctly in Docsify:

# [Lesson Title]

![Embed a video here](video-url)

## [Pre‑lecture quiz](quiz-url)

[Describe what we will learn]

### Introduction

Describe what will be covered

> Notes

### Prerequisite

What steps should have been covered before this lesson?

### Preparation

Preparatory steps to start this lesson

---
[Step through content in blocks]

## [Topic 1]

### Task:

Work together to progressively enhance your codebase:

```html
<!-- Example code block -->

✅ Knowledge Check - use this moment to stretch students' knowledge

[Topic 2]

🚀 Challenge: Add a challenge for students to work on collaboratively

Post‑lecture quiz

Review & Self Study

Assignment Due [MM/YY]: Assignment Name

### 3. Register the Lesson in the Root README

Locate the master lesson table in [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) under the **🗂️ Lessons** heading. Add a new row following the existing format:

```markdown
| 27 | [Progressive Web Apps](/11-progressive-web-apps/) | Service workers, caching, offline-first | [PWA Fundamentals](/11-progressive-web-apps/lesson-01/README.md) | Your Name |

The table columns represent:

1. Lesson number (sequential, two-digit)
2. Project/Topic name (with link to series folder)
3. Concepts taught (comma-separated keywords)
4. Linked lesson (path to specific lesson README)
5. Author (GitHub username or name)

Automating Lesson Creation with a Shell Script

For contributors adding multiple lessons, automate the scaffolding process:

#!/usr/bin/env bash

# Usage: ./add-lesson.sh 11 "Progressive Web Apps" "service-workers, offline" "your-name"

NUM=$1
TITLE=$2
TOPICS=$3
AUTHOR=$4

SERIES_DIR="${NUM}-$(echo "$TITLE" | tr '[:upper:]' '[:lower:]' | tr ' ' '-')"
LESSON_SLUG="lesson-01"

mkdir -p "$SERIES_DIR/$LESSON_SLUG"
cp -r lesson-template/* "$SERIES_DIR/$LESSON_SLUG/"

sed -i "s/\[Lesson Topic\]/$TITLE/g" "$SERIES_DIR/$LESSON_SLUG/README.md"

TABLE_LINE="| $NUM | [$TITLE]($SERIES_DIR) | $TOPICS | [$TITLE]($SERIES_DIR/$LESSON_SLUG/README.md) | $AUTHOR |"
sed -i "/^|.*|$/a $TABLE_LINE" README.md

echo "✅ Created $SERIES_DIR/$LESSON_SLUG and updated README.md"

Verifying Your Changes Locally

Before submitting a pull request, validate your lesson renders correctly:

# Install docsify CLI globally

npm install -g docsify-cli

# Start local server from repository root

docsify serve .

Navigate to http://localhost:3000 and verify:

• Your lesson appears in the left navigation panel
• All headings render with correct hierarchy
• Code blocks display with syntax highlighting
• Quiz links resolve correctly

Summary

• Folder naming: Use numeric prefixes (1-, 2-, 11-) to maintain curriculum order when you add new lessons to the curriculum structure.
• Template compliance: Always copy lesson-template/README.md to ensure consistent pedagogical sections (pre-quiz, tasks, challenge, post-quiz).
• Registry update: Append your lesson to the master table in the root README.md to enable navigation and translation workflows.
• Local testing: Use docsify serve to preview rendering before submitting your pull request.

Frequently Asked Questions

Do I need to manually create translation files when adding a new lesson?

No. The repository uses the Co-op-Translator GitHub Action to automatically copy English source files into each language folder under translations/. After your pull request merges to main, the workflow generates the necessary scaffolding for translators to populate.

What happens if I don't use the official lesson template?

While the curriculum will still function, omitting the lesson-template structure breaks the consistent learning experience. The Docsify navigation relies on specific heading hierarchies, and the automated translation pipeline expects standardized file paths. Always start with the template to ensure compatibility.

Can I add a lesson without updating the root README.md table?

Technically yes, but the lesson will not appear in the curriculum navigation, the generated PDF, or the translation workflow. The root README.md table serves as the single source of truth for the lesson registry. You must append your lesson details to this table for full integration.

How do I choose the correct numeric prefix for a new lesson series?

Examine the existing folders in the repository root to identify the highest current number. Series follow chronological order: 1-getting-started-lessons, 2-js-basics, 3-terrarium, etc. Use the next available integer (e.g., 11- if 10- is the highest) to ensure proper sorting in file explorers and documentation.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}