# Complete Frontmatter Schema Required for Lessons in docs/en.md

> Learn the essential frontmatter schema for lessons in rohitg00/ai-engineering-from-scratch. Ensure compliance with Title, Hook, Type, Languages, Prerequisites, Time, and Learning Objectives.

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

---

**Every lesson in the `rohitg00/ai-engineering-from-scratch` repository must include a structured frontmatter block at the top of its [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file with seven specific metadata fields—Title, Hook, Type, Languages, Prerequisites, Time, and Learning Objectives—to comply with the Lesson contract and pass automated validation.**

The `rohitg00/ai-engineering-from-scratch` curriculum maintains consistency across 435 lessons through a strict frontmatter schema defined in the project's **Lesson contract**. This standardized metadata block enables automated tooling to validate lesson structure, generate the website, and synchronize the README table of contents. Understanding the required frontmatter schema is essential for contributors adding new lessons or modifying existing documentation.

## The Seven Required Frontmatter Fields

According to the **Lesson contract** defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), every [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file must begin with a fenced markdown code block containing exactly seven metadata components. The block uses the `markdown` language tag and follows a precise hierarchical structure.

### Title and Hook

The frontmatter opens with a level-one heading and a blockquote teaser:

- **Title**: `# <Title>` — A human-readable lesson title using standard Markdown heading syntax.

- **Hook**: `> <One-line hook>` — A concise teaser appearing directly under the title that describes the lesson's value proposition.

### Classification and Technical Metadata

Three fields define the lesson's categorization and technical requirements:

- **Type**: `**Type:** <Learn | Build | Reference>` — Indicates the lesson's pedagogical purpose. Must be exactly one of these three values.
- **Languages**: `**Languages:** <comma-list>` — A comma-separated list of programming languages used in the lesson's `code/main.*` files. This must match the actual `main.*` files present in the lesson directory.
- **Prerequisites**: `**Prerequisites:** <comma-list or None>` — Other lesson slugs that must be completed first, or the literal string `None` if there are no dependencies.

### Duration and Learning Outcomes

The final two fields establish time expectations and educational goals:

- **Time**: `**Time:** ~<estimate>` — Approximate duration in minutes, prefixed with a tilde (e.g., `~30`).
- **Learning Objectives**: A level-two heading `## Learning Objectives` followed by 4-6 bullet points (using `- ` syntax), each starting with a verb describing what the learner will achieve.

## Automated Validation of the Frontmatter Schema

The repository enforces this schema through automated tooling that parses [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) files during CI/CD and local development workflows.

### Validation via audit_lessons.py

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script parses the frontmatter block to verify **compliance** with the Lesson contract. It checks that Languages entries match actual `main.*` files in the code directory, validates that Learning Objectives contain the correct number of bullet points (4-6), and ensures all required fields are present and formatted correctly.

### Site Generation and README Synchronization

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script extracts the Title and file paths from the frontmatter to construct [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), which drives the lesson website navigation. Missing or malformed frontmatter prevents the lesson from appearing in the generated website. Additionally, the README's automated table of contents pulls the Title directly from each lesson's frontmatter; inconsistencies break the auto-count logic that tracks the 435-lesson curriculum.

## Compliant Frontmatter Examples for docs/en.md

The following examples demonstrate valid frontmatter structures for single-language and multi-language lessons.

### Single-Language Python Lesson

```markdown

# Gradient Clipping and AMP

> Master gradient clipping and automatic mixed precision in PyTorch.

**Type:** Build
**Languages:** Python
**Prerequisites:** 45-gradient-checkpointing
**Time:** ~30

## Learning Objectives

- Explain why gradient clipping stabilizes training.
- Implement torch.nn.utils.clip_grad_norm_.
- Configure AMP with torch.cuda.amp.
- Compare training speed with and without AMP.
- Evaluate model quality after clipping.

```

### Multi-Language Lesson (Python and TypeScript)

```markdown

# Multi‑Agent Coordination Protocol

> Design a communication protocol for distributed agents.

**Type:** Learn
**Languages:** Python, TypeScript
**Prerequisites:** 21-agent-economies, 03-communication-protocols
**Time:** ~45

## Learning Objectives

- Describe the role of a coordination protocol.
- Define a JSON schema for agent messages.
- Implement a broadcaster in Python.
- Implement a subscriber in TypeScript.
- Simulate a simple multi‑agent scenario.

```

## Summary

- **Seven mandatory fields**: Title, Hook, Type, Languages, Prerequisites, Time, and Learning Objectives must appear in every [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) frontmatter block.
- **Strict formatting**: The block must be wrapped in a fenced markdown code block with the `markdown` specifier, following the exact hierarchical structure defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).
- **Automation dependency**: [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validates compliance, while [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) and README generators rely on this schema for site rendering and table-of-contents generation.
- **Language matching**: The **Languages** field must correspond exactly to the `main.*` files present in the lesson's code directory.

## Frequently Asked Questions

### What happens if my docs/en.md file is missing required frontmatter fields?

The [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) validation script will flag the lesson as non-compliant during automated checks. Missing frontmatter also prevents the lesson from appearing in the website generated by [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) and breaks the README's automated lesson counter, effectively excluding the content from the curriculum index.

### Can a single lesson specify multiple programming languages in the frontmatter?

Yes. The **Languages** field accepts a comma-separated list (e.g., `Python, TypeScript`) when the lesson contains multiple `main.*` files. However, every language listed must have a corresponding `main.{ext}` file in the lesson's code directory, or [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) will report a validation error.

### Where is the frontmatter schema contract formally defined?

The **Lesson contract** is formally specified in the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file at the repository root. This document defines the exact syntax, field order, and validation rules for the frontmatter block in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) files, serving as the authoritative reference for the 435-lesson curriculum standard.

### How many learning objectives must a lesson include?

The schema requires exactly **4 to 6 bullet points** under the `## Learning Objectives` heading. Each bullet must start with a verb describing a measurable skill or knowledge outcome. The [`audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/audit_lessons.py) script explicitly counts these bullets and fails validation if the count falls outside this range.