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

> Learn the essential seven-element frontmatter requirements for docs en md files in AI Engineering From Scratch. Ensure automated catalog generation and CI validation.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: tutorial
- Published: 2026-09-02

---

**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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). Each lesson's [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 70-86](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md#L70-L86), every [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.py) and [`code/main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/code/main.ts) exist, you must specify `python, typescript`. The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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)

```markdown

# 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)

```markdown

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) must appear in every [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.