docs/en.md Frontmatter Requirements for AI Engineering From Scratch Lessons

Every lesson in the AI Engineering From Scratch curriculum must declare a strict seven-element metadata block at the top of its docs/en.md file to enable automated catalog generation, README table updates, and CI validation.

The rohitg00/ai-engineering-from-scratch repository enforces a rigorous documentation contract defined in AGENTS.md. Each lesson's docs/en.md frontmatter drives the build system and ensures consistent metadata across the entire curriculum.

The Seven Required Frontmatter Fields

According to the specification in [AGENTS.md lines 70-86](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md#L70-L86), every docs/en.md file must open with these elements in exact order:

Title and Hook

The first line must be an ATX-style H1 heading (# <Title>) containing the human-readable lesson name. Immediately follow with a blockquote line starting with > to provide a concise one-line hook capturing the lesson's purpose.

Type Classification

Declare the lesson category using **Type:** followed by one of three allowed values: Learn, Build, or Reference.

Language Specifications

The **Languages:** field requires a comma-separated list that exactly matches the file extensions of main.* files in the lesson's code/ directory. For example, if code/main.py and code/main.ts exist, you must specify python, typescript. The scripts/audit_lessons.py validation script compares this metadata against actual filesystem contents; any mismatch causes CI checks to fail.

Prerequisites

List upstream dependencies using **Prerequisites:** followed by comma-separated lesson slugs (e.g., 01-linear-algebra-basics, 02-gradient-descent), or the literal string None if the lesson has no dependencies.

Time Estimates

Indicate required effort using **Time:** prefixed with the tilde character (~) and a number of minutes, such as ~45 or ~30.

Learning Objectives

Conclude the metadata block with a blank line, then the heading ## Learning Objectives followed by 4-6 bullet points. Each bullet must start with an action verb like "Implement", "Explain", or "Derive".

Validation and Enforcement

The repository uses scripts/audit_lessons.py to programmatically verify frontmatter compliance. This script validates that the **Languages:** field aligns with code/main.* extensions and ensures all required fields are present. The root README.md relies on this metadata to generate lesson table rows with proper markdown links during site builds.

Correct Frontmatter Examples

Single-Language Lesson (Python)

# Backpropagation from Scratch

> Implement the back‑propagation algorithm without any external deep‑learning libraries.

**Type:** Build  
**Languages:** python  
**Prerequisites:** 01-linear-algebra-basics, 02-gradient-descent  
**Time:** ~45

## Learning Objectives

- Derive the back‑propagation equations from first principles.  
- Write a pure‑numpy implementation of a multi‑layer perceptron.  
- Verify gradient correctness with numerical checks.  
- Train the network on a simple dataset and analyze convergence.  

Multi-Language Lesson (Python and TypeScript)

# Multi‑Modal Tokenizer

> Create a tokenizer that works across Python and TypeScript runtimes.

**Type:** Learn  
**Languages:** python, typescript  
**Prerequisites:** 03-tokenization-basics, 04-utf8-handling  
**Time:** ~30

## Learning Objectives

- Explain token‑stream construction for text and binary data.  
- Implement a shared tokenizer library in both languages.  
- Write unit tests that run in both runtimes.  
- Benchmark tokenization speed and discuss trade‑offs.  

Summary

• Seven mandatory fields defined in AGENTS.md must appear in every docs/en.md file.
• The **Languages:** field must exactly match file extensions found in the code/ directory.
• Prerequisites use comma-separated lesson slugs or the literal None.
• Time estimates require the ~ prefix followed by minutes.
• The scripts/audit_lessons.py CI script enforces compliance and fails builds on mismatches.

Frequently Asked Questions

What happens if the Languages field does not match the code/ directory contents?

The scripts/audit_lessons.py validation script will detect the discrepancy and cause the CI pipeline to fail. The check ensures that metadata accurately reflects the actual implementation files present in the lesson's code/ directory.

Can I omit the Prerequisites field if my lesson has no dependencies?

No. You must explicitly include **Prerequisites:** None rather than omitting the field. The validation scripts require this field to be present for every lesson to maintain consistent parsing across the curriculum.

How many Learning Objectives should a lesson include?

The specification requires exactly 4 to 6 bullet points under the ## Learning Objectives heading. Each bullet must begin with an action verb such as "Implement", "Explain", or "Derive" to maintain instructional clarity.

Where is the frontmatter contract formally defined?

The complete contract is documented in [AGENTS.md lines 70-86](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md#L70-L86) within the rohitg00/ai-engineering-from-scratch repository. This file serves as the authoritative source for the metadata structure and validation rules.

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