How ROADMAP.md Tracks the Completion Status of Lessons in ai-engineering-from-scratch

ROADMAP.md tracks lesson completion status by embedding ✅, 🚧, and ⬚ emojis directly into markdown phase headers and lesson tables, which site/build.js parses into canonical complete, in-progress, and planned strings to power the project website and site/data.js.

The rohitg00/ai-engineering-from-scratch repository treats ROADMAP.md as the single source of truth for curriculum progress. This file blends human-readable visual markers with a deterministic parsing pipeline, ensuring instructors and automated tooling agree on exactly which lessons are finished, active, or pending.

The Three-Glyph Status Legend

ROADMAP.md encodes every lesson state with one of three Unicode glyphs. These symbols provide an at-a-glance view of the entire curriculum without requiring readers to interpret metadata files or JSON schemas.

• ✅ Complete – the lesson has been delivered and its code or tests pass.
• 🚧 In Progress – active development is underway but the lesson is not yet finished.
• ⬚ Planned – the lesson is scheduled for future work and has not been started.

Where Status Appears in ROADMAP.md

The emojis appear in two specific locations inside the markdown file. Phase headers show aggregate progress, while individual lesson rows provide granular, at-a-glance detail for every curriculum item.

Phase Headers

Each phase declares its overall health in the section title itself. The emoji appears after an em-dash, making the aggregate state visible before readers scroll to individual lessons.

## Phase 0: Setup & Tooling — ✅

Lesson Table Rows

Within each phase, lessons live in markdown tables with a dedicated Status column. Every row binds a lesson name to its current glyph so readers can scan progress instantly, as implemented in rohitg00/ai-engineering-from-scratch.

| # | Lesson | Status | Est. |

|---|--------|--------|------|
| 01 | Dev Environment | ✅ | ~75 min |

How site/build.js Parses ROADMAP.md into Structured Data

The build script located at site/build.js scans ROADMAP.md line-by-line to extract the visual state and convert it into machine-readable strings. This normalization occurs around lines 30–48 of the script and removes all emoji-handling complexity from downstream consumers.

Phase-Level Extraction

A regular expression targets phase headers to capture the trailing emoji. It then maps that symbol to a canonical string representing the overall phase health.

// Phase header → overall phase status
const phaseMatch = line.match(/^##\s+Phase\s+(\d+).*?—\s*(✅|🚧|⬚)/);
if (phaseMatch) {
  const statusEmoji = phaseMatch[2];
  currentPhaseStatus = statusEmoji === '✅' ? 'complete'
                    : statusEmoji === '🚧' ? 'in-progress' : 'planned';
  // store under statuses[currentPhase]...
}

Lesson-Level Extraction

After identifying a phase, a second regex matches table rows containing lesson data. It extracts the lesson name and status emoji, then stores the mapped value in the statuses object for later consumption.

// Lesson row → per-lesson status
const lessonMatch = line.match(/^\|\s*\d+\s*\|\s*(.+?)\s*\|\s*(✅|🚧|⬚)\s*\|/);
if (lessonMatch) {
  const statusEmoji = lessonMatch[2];
  const status = statusEmoji === '✅' ? 'complete'
               : statusEmoji === '🚧' ? 'in-progress' : 'planned';
  statuses[currentPhase].lessons[lessonName] = status;
}

Feeding the Website Pipeline

Once parsed, the statuses object is merged with lesson content extracted from README.md. During this alignment step inside the build pipeline, the script performs a fuzzy match between lesson names documented in the roadmap and those described in the readme.

let status = 'planned';
if (roadmapPhase) {
  // fuzzy match lesson name → status from ROADMAP
  for (const [rName, rStatus] of Object.entries(roadmapPhase.lessons)) {
    if (matchesLessonName(rName, lessonName)) {
      status = rStatus;
      break;
    }
  }
}

The final aggregated data is written to site/data.js, where the status strings drive visual icons, progress indicators, and curriculum queries on the project website.

Summary

• ROADMAP.md embeds ✅, 🚧, and ⬚ emojis in phase headers and lesson tables to indicate completion, in-progress, and planned states.
• site/build.js uses two targeted regular expressions to extract and normalize these emojis into machine-readable strings around lines 30–48.
• The resulting statuses object is merged with README.md content and serialized to site/data.js for the website frontend.

Frequently Asked Questions

What do the ✅, 🚧, and ⬚ emojis mean in ROADMAP.md?

The ✅ emoji marks a lesson or phase as Complete, meaning it has been delivered and its associated code or tests pass. The 🚧 emoji indicates the item is In Progress, while the ⬚ emoji means it is Planned but not yet started.

How does site/build.js know which status emoji belongs to which lesson?

The script runs two regex passes over ROADMAP.md. The first matches ## Phase … — [emoji] to set the current phase context, and the second matches | ## | Lesson Name | [emoji] | to bind each row's emoji to that phase's statuses object under the lesson name key.

Can I update a lesson's completion status by editing ROADMAP.md manually?

Yes. Because ROADMAP.md is the single source of truth, changing an emoji in the markdown table and re-running the build script will update the canonical status in site/data.js. No separate database or configuration file needs to be modified.

Where does the parsed status data end up after the build script runs?

The normalized status values are stored in a JavaScript object that is merged with README.md lesson metadata and emitted to site/data.js. This file powers the visual icons and progress indicators rendered on the project website.

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