How to Add Assignments or Evaluations to Lessons in Web-Dev-For-Beginners

Create an assignment.md file in the lesson folder and link to it from the lesson's README.md using a relative markdown path on the "Assignment Due" line.

The microsoft/Web-Dev-For-Beginners curriculum uses a standardized folder structure to organize lessons and assessments. Every lesson directory contains a README.md for instructional content and an assignment.md for evaluations. To add assignments or evaluations to lessons, you modify these two files following the repository's established template patterns.

Understanding the Lesson Structure in Web-Dev-For-Beginners

The repository maintains consistency through a master lesson-template folder located at the repository root. This template defines the file structure that every concrete lesson duplicates.

Each lesson folder (such as 2-js-basics/1-data-types/) contains:

• README.md: The primary lesson content, learning objectives, and instructional text.
• assignment.md: A placeholder or populated file containing exercises, project descriptions, and evaluation rubrics.
• Supporting subfolders like images/ or solutions/ for assets.

The lesson-template/README.md contains an "Assignment Due" placeholder on line 51 where you insert the link to your evaluation file. The lesson-template/assignment.md provides a skeleton structure including a rubric table that you can customize for specific learning objectives.

How to Add Assignments to Lessons

Adding an assignment requires creating the assessment content and linking it from the main lesson page. Follow these steps to ensure the assignment appears correctly in the curriculum navigation.

Step 1: Create the assignment.md File

Navigate to the specific lesson folder where you want to add the evaluation. Create a new file named assignment.md (or edit the existing placeholder). Use the template from lesson-template/assignment.md as your starting point.

The file should include:

• A clear title and instructions section.
• Specific tasks or exercises for learners to complete.
• Learning objectives that align with the lesson content.

Step 2: Link the Assignment in the Lesson README

Open the lesson's README.md file and locate the "Assignment Due" line (approximately line 51 in the template). Replace the placeholder text with a relative markdown link pointing to your assignment.md file.

The syntax follows this pattern:

**Assignment Due [Month Year]**: [Assignment Title](assignment.md)

For example, in 2-js-basics/1-data-types/README.md, the link appears as:

**Assignment Due Sep 2026**: [Data Types Practice](assignment.md)

This relative path ensures the link works correctly whether viewed on GitHub or through a local documentation server.

Step 3: Add an Evaluation Rubric (Optional)

To provide clear grading criteria, include a rubric table in your assignment.md file. The template includes a placeholder table that you can customize with specific criteria, performance levels, and point values.

A standard rubric uses this markdown structure:

| Criteria | Exemplary (90-100%) | Adequate (70-89%) | Needs Improvement (<70%) |
|----------|---------------------|-------------------|--------------------------|
| Code correctness | All test cases pass | Minor logic errors | Does not compile or run |
| Documentation | Clear comments and README | Basic comments | Missing or unclear docs |

Complete Example: Adding an Assignment to the Data Types Lesson

Here is the complete workflow for adding an assignment to the JavaScript Data Types lesson located at 2-js-basics/1-data-types/.

First, create or edit 2-js-basics/1-data-types/assignment.md:

# Data Types Practice

## Instructions

Write a short essay (200-300 words) describing the difference between *primitive* and *reference* types in JavaScript.

Provide at least three code examples that demonstrate:
1. A primitive value being copied by value.
2. An object being mutated after assignment.
3. Using `Array.isArray` to detect an array type.

## Rubric

| Criteria | Exemplary (90-100%) | Adequate (70-89%) | Needs Improvement (<70%) |
|----------|---------------------|-------------------|--------------------------|
| Explanation clarity | Very clear, no jargon | Mostly clear | Vague or incorrect |
| Code correctness | All snippets run | Minor bugs | Does not run |
| Insight depth | Shows deeper understanding | Basic concepts | Surface-level only |

Next, update 2-js-basics/1-data-types/README.md to link to this assignment. Locate the assignment placeholder and replace it with:

**Assignment Due Sep 2026**: [Data Types Practice](assignment.md)

After committing these changes, the lesson page automatically renders the assignment link, and learners can access the evaluation criteria directly from the curriculum navigation.

Summary

• The microsoft/Web-Dev-For-Beginners repository uses a standardized lesson-template structure where every lesson contains README.md for content and assignment.md for evaluations.
• To add assignments or evaluations to lessons, create an assignment.md file in the specific lesson folder, populate it with instructions and an optional rubric, then link to it from the lesson's README.md using the "Assignment Due" line.
• Use relative paths like (assignment.md) when linking to ensure compatibility across GitHub and local documentation servers.
• The template files in lesson-template/ provide the skeleton structure for both lesson content and assignment rubrics, ensuring consistency across the curriculum.

Frequently Asked Questions

Where is the assignment template located in the repository?

The master assignment template is located at lesson-template/assignment.md in the repository root. This file contains the standard structure including placeholder sections for instructions, tasks, and a grading rubric. Individual lesson folders may contain empty or placeholder assignment.md files that you should populate using this template as a reference.

How do I link assignments in the lesson README?

You link assignments by editing the "Assignment Due" line in the lesson's README.md file, typically found around line 51 in the template. Replace the placeholder text with a relative markdown link in the format **Assignment Due [Date]**: [Assignment Title](assignment.md). This creates a clickable link that renders correctly on GitHub and points learners directly to the evaluation file.

Can I add multiple assignments to one lesson?

While the standard template supports one primary assignment.md file per lesson, you can create additional evaluation files with descriptive names (e.g., assignment-bonus.md or project-evaluation.md) and link to them from the main README.md or from within the primary assignment file. However, for consistency with the rest of the curriculum, it is recommended to consolidate evaluations into the single assignment.md file using sections or the rubric table to differentiate tasks.

What format should the evaluation rubric use?

The evaluation rubric should use a markdown table format with columns for criteria and performance levels. The standard template uses three performance tiers: "Exemplary (90-100%)", "Adequate (70-89%)", and "Needs Improvement (<70%)". Each row represents a specific evaluation criterion such as code correctness, documentation quality, or conceptual understanding. This table format renders clearly on GitHub and provides learners with transparent grading expectations before they begin the assignment.

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