How the Lesson Navigation Flow Is Structured in ML-For-Beginners

The ML-For-Beginners repository implements a dual navigation system combining a global table of contents in _toc.yml with linear "Next Lesson" badges generated by scripts/generate_nav_badges.py, allowing learners to follow a guided path or jump between self-contained modules.

The lesson navigation flow in the Microsoft ML-For-Beginners curriculum is designed to support both sequential learning and flexible exploration. This open-source machine learning course organizes content into modular directories under modules/, with each lesson containing a README.md for theory and a Jupyter notebook for hands-on practice. The navigation structure relies on Jekyll site generation, a centralized YAML configuration, and automated badge generation to create a cohesive learning experience.

Module-Level Directory Structure

Each lesson resides in a self-contained folder under modules/, typically named with a numeric prefix such as 01-introduction or 02-linear-regression. Every module follows a consistent file organization pattern that ensures self-containment and navigability.

The README.md file in each module serves as the theoretical introduction, containing learning objectives and a "Next Lesson" navigation badge that points to the subsequent module. The notebook.ipynb file contains the interactive Jupyter notebook implementing the hands-on coding exercises. Optional directories include data/ for sample datasets required by the notebook and assets/ for images or diagrams referenced by the markdown.

This structure ensures that any module can function independently while maintaining consistent navigation patterns across the curriculum.

Global Table of Contents Configuration

The site-wide navigation sidebar is controlled by _toc.yml at the repository root. This YAML file enumerates all modules in their intended learning sequence, serving as the single source of truth for the lesson navigation flow.

Example structure from _toc.yml:

- title: Introduction
  url: /modules/01-introduction/
- title: Linear Regression
  url: /modules/02-linear-regression/
- title: Classification
  url: /modules/03-classification/

Jekyll's jekyll-toc-generator plugin consumes this file during the build process to render the navigation sidebar. Modifying the lesson order or adding new modules requires only updating _toc.yml; the site structure regenerates automatically upon the next build.

Jekyll Site Generation and Module Integration

The repository leverages GitHub Pages with Jekyll to transform the markdown and notebook files into a static learning site. The _config.yml file specifies critical navigation parameters that bind the lesson navigation flow components together.

Key configuration excerpts:

theme: minima
toc: true
toc_file: _toc.yml
include:
  - modules/**/*.md
  - modules/**/*.ipynb

The include directive ensures Jekyll processes both markdown lesson introductions and Jupyter notebooks, rendering them as browsable HTML pages. The toc_file parameter binds the global navigation to the _toc.yml configuration, creating a unified lesson navigation flow across all generated pages.

Automated Navigation Badge Generation

While the global TOC provides sidebar navigation, linear progression through the curriculum is facilitated by "Next Lesson" and "Previous Lesson" badges embedded in each module's README.md. These badges are automatically generated and maintained by scripts/generate_nav_badges.py.

This Python script parses _toc.yml to determine module sequence, then computes adjacent lessons for each module. It subsequently rewrites the navigation badges in each README to ensure consistent linear flow. For example, the script generates markdown like:

[![Next Lesson](https://img.shields.io/badge/Next%20Lesson-02--linear--regression-blue)](../02-linear-regression/README.md)

Running this script during the CI pipeline ensures that navigation badges remain synchronized with any curriculum restructuring, eliminating manual maintenance of inter-module links.

Complete User Journey Through the Lesson Navigation Flow

The lesson navigation flow supports two distinct learning patterns: guided sequential progression and flexible topic jumping.

Sequential Learning Path:

1. The learner starts at the repository root README.md, which presents an overview and a "Start Learning" button linking to modules/01-introduction/README.md.
2. Within each module, the learner reviews the theoretical content in the local README.md, then launches the interactive notebook via the "Open in Binder" badge.
3. Upon completing the hands-on exercises, the learner clicks the "Next Lesson" badge to advance to the subsequent module's README.
4. This linear progression continues through the sequence defined in _toc.yml.

Flexible Exploration Path:

• At any point, the learner can reference the global sidebar navigation generated from _toc.yml to jump to specific topics like Classification or Deep Learning without following the linear sequence.
• Because each module is self-contained with its own data/ and assets/, jumping between non-consecutive lessons does not create dependency issues.

This dual navigation architecture ensures the ML-For-Beginners curriculum accommodates both structured classroom use and self-directed learning.

Summary

• The lesson navigation flow in ML-For-Beginners relies on a modular directory structure under modules/, where each lesson contains a README.md for theory and a notebook.ipynb for practice.
• Global navigation is controlled by _toc.yml, which Jekyll processes to generate the site sidebar, serving as the single source of truth for module ordering.
• Linear progression is maintained by automated "Next Lesson" badges generated by scripts/generate_nav_badges.py, which parses _toc.yml to create accurate inter-module links.
• The Jekyll configuration in _config.yml binds these components together, ensuring both markdown and Jupyter notebooks render as browsable pages with consistent navigation.

Frequently Asked Questions

How do I add a new lesson to the ML-For-Beginners navigation flow?

To add a new lesson, create a directory under modules/ following the naming convention (e.g., 07-deep-learning), add your README.md and notebook.ipynb, then append the module entry to _toc.yml. Run python scripts/generate_nav_badges.py to update the navigation badges, or let the CI pipeline handle this automatically upon your pull request.

Can learners jump between non-consecutive modules without breaking dependencies?

Yes, the lesson navigation flow supports flexible exploration because each module is self-contained. Every module includes its own data/ directory and standalone README.md, so learners can navigate directly to any topic via the global sidebar generated from _toc.yml without requiring completion of previous lessons.

What happens if the lesson order needs to be reorganized?

Reordering lessons requires only modifying the sequence in _toc.yml. The scripts/generate_nav_badges.py script parses this file during the next build to recalculate "Next" and "Previous" links for all affected modules, ensuring the linear navigation badges remain synchronized with the new structure without manual editing of individual README files.

How does the repository handle navigation for Jupyter notebooks versus markdown files?

The Jekyll site generator processes both file types equally through the include directive in _config.yml, which specifies modules/**/*.md and modules/**/*.ipynb. This ensures that clicking a module link in the _toc.yml-generated sidebar renders the appropriate content type—markdown for theoretical introductions and the notebook viewer for interactive coding exercises—within the same lesson navigation flow.

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