Mandatory Frontmatter Components for a Lesson’s docs/en.md File

Every lesson’s docs/en.md file must begin with seven specific frontmatter components—Title, One-line hook, Type, Languages, Prerequisites, Time, and Learning Objectives—to be recognized by the curriculum’s automation tooling.

The rohitg00/ai-engineering-from-scratch repository maintains a rigorous curriculum structure spanning 435 lessons. To ensure consistency across the entire course, each lesson must follow a strict Lesson contract defined in AGENTS.md. Understanding the mandatory frontmatter components for a lesson’s docs/en.md file is essential for contributors and curriculum maintainers who need to pass validation scripts and generate proper documentation.

The Seven Mandatory Frontmatter Components

According to the Lesson contract in AGENTS.md, the frontmatter must appear in the exact order specified below. The repository’s tooling, including scripts/audit_lessons.py, parses these fields to generate README tables, site navigation, and quiz scaffolding.

Title

The Title provides the lesson’s human-readable name and must be formatted as a Markdown H1 heading. This appears as the first line of the file.

# Linear Regression from Scratch

One-line Hook

The One-line hook is a concise, attention-grabbing sentence that summarizes the lesson’s value proposition. It must use blockquote syntax (>) immediately following the title.

> Build a simple linear regression model without using external ML libraries.

Type

The Type categorizes the lesson into one of three pedagogical buckets: Learn, Build, or Reference. This must be formatted in bold with the exact label.

**Type:** Build

Languages

The Languages field lists all programming languages used in the lesson’s code/ directory. The values must match the main.* file extensions and be provided as a comma-separated list.

**Languages:** Python, Rust

Prerequisites

The Prerequisites field identifies other lessons that should be completed first. If there are no dependencies, the literal string "None" must be used.

**Prerequisites:** 01-intro-to-python, 02-numpy-basics

Or:

**Prerequisites:** None

Time

The Time field provides an estimated duration for completing the lesson, expressed in minutes with a tilde prefix.

**Time:** ~30

Learning Objectives

The Learning Objectives section defines 4–6 actionable outcomes the learner will achieve. This requires an H2 heading followed by a bulleted list using dashes.

## Learning Objectives

- Implement the normal equation from first principles.
- Generate synthetic data and fit a regression line.
- Evaluate model performance using mean squared error.
- Visualise the regression result with Matplotlib.

Enforcement via Audit Scripts

The repository enforces these requirements through scripts/audit_lessons.py, which validates that each docs/en.md complies with the mandatory frontmatter structure. Lessons missing any component or using incorrect formatting (such as indented code blocks instead of ATX headings) will fail the audit and be excluded from the generated curriculum index.

Real-world examples can be found throughout the repository, such as in phases/10-llms-from-scratch/01-tokenizers/docs/en.md, which demonstrates the exact pattern expected by the tooling.

Minimal Working Example

Below is a complete, valid frontmatter block that satisfies all requirements for a lesson’s docs/en.md file:

# Linear Regression from Scratch

> Build a simple linear regression model without using external ML libraries.

**Type:** Build
**Languages:** Python
**Prerequisites:** None
**Time:** ~30

## Learning Objectives

- Implement the normal equation from first principles.
- Generate synthetic data and fit a regression line.
- Evaluate model performance using mean squared error.
- Visualise the regression result with Matplotlib.

When this block is added to a lesson’s docs/en.md, the curriculum’s automation scripts recognize it immediately, populating the lesson’s entry in README.md and the site’s data layer.

Summary

• Seven components are mandatory: Title, One-line hook, Type, Languages, Prerequisites, Time, and Learning Objectives.
• Order matters: The components must appear in the exact sequence defined in AGENTS.md.
• Specific formatting required: Use H1 for Title, blockquote for the hook, bold labels for metadata fields, and H2 with bullet lists for Learning Objectives.
• Validation is automatic: scripts/audit_lessons.py checks compliance across all 435 lessons in the curriculum.

Frequently Asked Questions

What happens if I omit the One-line hook or use the wrong format?

The lesson will fail validation in scripts/audit_lessons.py and will not be indexed in the README or site navigation. The hook must use blockquote syntax (>) and appear immediately after the H1 title.

Can I use multiple languages in the Languages field?

Yes. List them as a comma-separated string (e.g., **Languages:** Python, Rust, Go). Ensure these match the file extensions of the main.* files in the lesson’s code/ directory.

Is the Time field strictly enforced?

While the format **Time:** ~<minutes> is mandatory, the estimate itself is a guideline. However, the field must be present for the lesson to pass the audit and appear in the curriculum tables.

Where is the Lesson contract documented?

The complete specification resides in AGENTS.md under the Lesson contract section, which defines the mandatory frontmatter structure for all docs/en.md files in the repository.

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