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

> Understand the ML-For-Beginners lesson navigation flow. Explore the dual system combining a global table of contents and linear next lesson badges for guided learning.

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

---

**The ML-For-Beginners repository implements a dual navigation system combining a global table of contents in [`_toc.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_toc.yml) with linear "Next Lesson" badges generated by [`scripts/generate_nav_badges.py`](https://github.com/microsoft/ML-For-Beginners/blob/main/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`](https://github.com/microsoft/ML-For-Beginners/blob/main/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`](https://github.com/microsoft/ML-For-Beginners/blob/main/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`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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`](https://github.com/microsoft/ML-For-Beginners/blob/main/_toc.yml):

```yaml
- 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`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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`](https://github.com/microsoft/ML-For-Beginners/blob/main/_config.yml) file specifies critical navigation parameters that bind the lesson navigation flow components together.

Key configuration excerpts:

```yaml
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`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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`](https://github.com/microsoft/ML-For-Beginners/blob/main/README.md). These badges are automatically generated and maintained by [`scripts/generate_nav_badges.py`](https://github.com/microsoft/ML-For-Beginners/blob/main/scripts/generate_nav_badges.py).

This Python script parses [`_toc.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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:

```markdown
[![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`](https://github.com/microsoft/ML-For-Beginners/blob/main/README.md), which presents an overview and a "Start Learning" button linking to [`modules/01-introduction/README.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/modules/01-introduction/README.md).
2. Within each module, the learner reviews the theoretical content in the local [`README.md`](https://github.com/microsoft/ML-For-Beginners/blob/main/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`](https://github.com/microsoft/ML-For-Beginners/blob/main/_toc.yml).

**Flexible Exploration Path:**

- At any point, the learner can reference the **global sidebar navigation** generated from [`_toc.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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`](https://github.com/microsoft/ML-For-Beginners/blob/main/README.md) for theory and a `notebook.ipynb` for practice.
- **Global navigation** is controlled by [`_toc.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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`](https://github.com/microsoft/ML-For-Beginners/blob/main/scripts/generate_nav_badges.py), which parses [`_toc.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_toc.yml) to create accurate inter-module links.
- The **Jekyll configuration** in [`_config.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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`](https://github.com/microsoft/ML-For-Beginners/blob/main/README.md) and `notebook.ipynb`, then append the module entry to [`_toc.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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`](https://github.com/microsoft/ML-For-Beginners/blob/main/README.md), so learners can navigate directly to any topic via the global sidebar generated from [`_toc.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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`](https://github.com/microsoft/ML-For-Beginners/blob/main/_toc.yml). The [`scripts/generate_nav_badges.py`](https://github.com/microsoft/ML-For-Beginners/blob/main/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`](https://github.com/microsoft/ML-For-Beginners/blob/main/_config.yml), which specifies `modules/**/*.md` and `modules/**/*.ipynb`. This ensures that clicking a module link in the [`_toc.yml`](https://github.com/microsoft/ML-For-Beginners/blob/main/_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.