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

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

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:

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:

touch notebook.ipynb

Insert a markdown cell containing:

# Polynomial Regression

And a code cell containing:

print("Hello polynomial regression!")

This matches the pattern used in 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:

mkdir images

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

6. Provide Solution Files (Optional)

If providing reference implementations:

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:

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:

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:

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

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)	High-level overview, links to all modules
2-Regression/README.md	Module index – lists each regression lesson
2-Regression/1-Tools/README.md	Template lesson showing required sections and asset layout
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 (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.

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