# How to Add New Lessons to the ML-For-Beginners Curriculum: A Step-by-Step Guide

> Add new lessons to ML-For-Beginners by creating a numbered subfolder, README.md, and notebook. Follow this guide to contribute to the ML curriculum structure at microsoft/ML-For-Beginners.

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

---

**To add new lessons to the ML-For-Beginners curriculum, create a numbered lesson subfolder within the appropriate module directory, populate it with a README.md following the established heading hierarchy, a starter notebook.ipynb, and optional images/ and solution/ directories.**

The Microsoft ML-For-Beginners repository follows a strict modular architecture that enables automated documentation generation and consistent learner experiences. When you add new lessons to the ML-For-Beginners curriculum, you must adhere to the existing folder naming conventions and file structures that power the Docsify navigation and quiz integration systems.

## Understanding the Curriculum Architecture

### Module and Lesson Folder Structure

The curriculum organizes content into **module folders** (e.g., `2-Regression`, `3-Web-App`, `4-Classification`). Each module contains a series of **lesson sub-folders** that follow a consistent layout:

```

<module>/                      # e.g. 2-Regression

│
├─ <lesson-number>-<title>/    # e.g. 1-Tools

│   ├─ README.md               # lesson content, instructions, quizzes

│   ├─ notebook.ipynb          # starter Jupyter notebook

│   ├─ images/                 # optional screenshots / diagrams

│   └─ solution/
│       ├─ R/                  # optional R-markdown solution

│       └─ Python/             # or just source files

```

### Required Files and Assets

Every new lesson requires specific files to maintain compatibility with the curriculum's automated tooling:

- **README.md**: Must include pre-lecture quiz badges, introduction, installation instructions, exercise blocks, challenge sections, and post-lecture quiz links. Reference [`2-Regression/1-Tools/README.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/2-Regression/1-Tools/README.md) for the exact heading hierarchy and quiz link patterns.
- **notebook.ipynb**: Starter Jupyter notebook containing at least one markdown cell with the lesson title and a code cell with a greeting or initial setup.
- **images/**: Directory for screenshots, sketchnotes, and diagrams referenced via relative paths.
- **solution/**: Optional directory containing completed implementations in `solution/R/` or `solution/Python/` subdirectories.

## Step-by-Step Guide to Adding a New Lesson

### 1. Select the Target Module

Navigate to the appropriate module directory where your lesson fits within the curriculum flow. For example, if adding a polynomial regression lesson, navigate to `2-Regression/`.

### 2. Create the Lesson Directory

Use a numeric prefix that follows the existing sequence and a concise, descriptive title:

```bash
cd 2-Regression
mkdir 5-PolynomialRegression
cd 5-PolynomialRegression

```

The folder name becomes part of the URL for GitHub rendering and the Docsify site navigation.

### 3. Author the README.md Content

Copy an existing lesson README as a template and modify the content:

```bash
cp ../1-Tools/README.md README.md

```

Edit the file to include:
- Pre-lecture quiz badge linking to the quiz app
- "This lesson is available in R!" link (optional)
- Introduction section
- Installations and configurations (if new tools are needed)
- Exercise blocks using the numbered pattern `1. ...`, `2. ...` so the auto-grader can parse them
- Challenge, Review & Self-Study, Assignment, and Post-lecture quiz links

Maintain relative links (`../data/...`, `./images/...`) because the Docsify generator expects them.

### 4. Add the Starter Notebook

Create the `notebook.ipynb` file with the required structure:

```bash
touch notebook.ipynb

```

Insert a markdown cell containing:

```markdown

# Polynomial Regression

```

And a code cell containing:

```python
print("Hello polynomial regression!")

```

This matches the pattern used in [`2-Regression/1-Tools/README.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/2-Regression/1-Tools/README.md) under the "Exercise – work with a notebook" block.

### 5. Include Supporting Assets

Create the images directory and add any screenshots or sketchnotes:

```bash
mkdir images

```

Reference these in your README using relative paths like `./images/sketchnote.png`.

### 6. Provide Solution Files (Optional)

If providing reference implementations:

```bash
mkdir -p solution/R
mkdir -p solution/Python

```

Copy completed notebooks or R-markdown files into these directories, mirroring the structure used in `4-Classification/1-Introduction/solution/R/`.

### 7. Commit and Verify

Stage and commit your changes:

```bash
git add 2-Regression/5-PolynomialRegression
git commit -m "Add new lesson: Polynomial Regression"
git push origin main

```

Verify the Docsify site by running the local server:

```bash
docsify serve

```

The new lesson should appear under its module in the navigation tree automatically.

## Code Examples for Automation

Here is the complete workflow for adding a lesson via command line:

```bash

# Navigate to the desired module

cd 2-Regression

# Create a new lesson folder (next numeric prefix)

mkdir 5-PolynomialRegression
cd 5-PolynomialRegression

# Initialise the README from a template

cp ../1-Tools/README.md README.md

# Edit the file: change titles, update quiz links, adjust exercises

# Add a starter notebook

touch notebook.ipynb

# Insert a markdown cell:

#   "# Polynomial Regression"

# And a code cell:

#   print("Hello polynomial regression!")

```

**Adding a solution for R:**

```bash
mkdir -p solution/R

# Copy a finished R markdown file (generated by the lesson author)

cp ../../solution/R/lesson_1.html solution/R/

```

## Key Files and Their Roles

| Path | Role |
|---|---|
| [README.md (repo root)](https://github.com/microsoft/ML-For-Beginners/blob/main/README.md) | High-level overview, links to all modules |
| [2-Regression/README.md](https://github.com/microsoft/ML-For-Beginners/blob/main/2-Regression/README.md) | Module index – lists each regression lesson |
| [2-Regression/1-Tools/README.md](https://github.com/microsoft/ML-For-Beginners/blob/main/2-Regression/1-Tools/README.md) | Template lesson showing required sections and asset layout |
| [4-Classification/1-Introduction/README.md](https://github.com/microsoft/ML-For-Beginners/blob/main/4-Classification/1-Introduction/README.md) | Another template, includes video thumbnail and challenge block |
| `lesson_folder/notebook.ipynb` | Starter Jupyter notebook that learners open first |
| `lesson_folder/images/` | Holds screenshots / sketchnotes referenced by the README |
| `lesson_folder/solution/` | Optional folder containing completed Python/R solutions (not shown to learners) |
| [`docsify.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/docsify.yml) (or equivalent build script) | Generates the navigation tree from the folder hierarchy (implicitly uses the consistent naming pattern) |

## Summary

- **Consistent folder naming** enables the automated Docsify navigation script to discover lessons without extra configuration.
- **Standard README structure** is parsed by the curriculum's quiz and assignment tooling (e.g., the `Assignment` markdown link is expected at the end of the file).
- **Relative asset links** guarantee that the documentation works both locally and on GitHub Pages.
- **Solution sub-folders** are ignored by the student-facing version of the repo (they live under `solution/` and are not rendered in the main content), keeping the learning experience clean while still providing reference code for instructors.

## Frequently Asked Questions

### What naming convention should I use for new lesson folders?

Use a numeric prefix followed by a descriptive title with no spaces, such as `5-PolynomialRegression`. This pattern ensures the Docsify navigation generator correctly orders lessons within the module and creates clean URLs for GitHub Pages rendering.

### How do I ensure my new lesson appears in the Docsify navigation?

The Docsify site automatically builds the navigation tree from the folder hierarchy. As long as you place your lesson folder inside a module directory (e.g., `2-Regression/`) and use the standard numeric prefix naming convention, the site will include it without manual configuration of the navigation sidebar.

### Can I add lessons in languages other than Python?

Yes. While the primary curriculum uses Python and Jupyter notebooks, you can provide alternative implementations by creating a `solution/R/` directory within your lesson folder. Place R-markdown files or R scripts there, and update the README to include the "This lesson is available in R!" link, mirroring the structure found in `4-Classification/1-Introduction/solution/R/`.

### Where should I place completed solution files?

Completed solutions belong in a `solution/` subdirectory within your lesson folder. Create `solution/Python/` for completed notebooks or Python scripts, and `solution/R/` for R implementations. These folders are implicitly excluded from the student-facing view of the curriculum while remaining accessible for instructors and contributors.