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

> Learn how to add new lessons to the curriculum structure in Web-Dev-For-Beginners. Follow simple steps to create folders, populate README files, and register your lesson.

- Repository: [Microsoft/Web-Dev-For-Beginners](https://github.com/microsoft/Web-Dev-For-Beginners)
- Tags: how-to-guide
- Published: 2026-02-27

---

**To add new lessons to the curriculum structure, create a numbered folder in the repository root, populate it with a [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) based on the `lesson-template`, and register the lesson in the master table within the root [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) that holds the actual lesson material, quizzes, and assignments.
- **Master registry**: The root [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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.

```bash

# 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.

```bash

# From repository root

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

```

Edit the generated [`README.md`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/README.md) to replace placeholders. The template requires specific heading hierarchy to render correctly in Docsify:

```markdown

# [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](quiz-url)

## Review & Self Study

**Assignment Due [MM/YY]**: [Assignment Name](assignment.md)

```

### 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:

```bash
#!/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:

```bash

# 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`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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`](https://github.com/microsoft/Web-Dev-For-Beginners/blob/main/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.