Lesson Frontmatter Format in docs/en.md: AI Engineering Curriculum Metadata

Every lesson's docs/en.md file must begin with a standardized frontmatter block containing seven required metadata fields that enable automated site generation and CI validation across the 435-lesson curriculum.

The rohitg00/ai-engineering-from-scratch repository organizes its curriculum using a strict lesson frontmatter format defined for each docs/en.md file. This metadata schema ensures consistency across all lessons, allowing automated tools to parse lesson details, build navigation, and enforce prerequisite chains.

Required Frontmatter Fields in docs/en.md

The frontmatter must appear at the very top of the file and includes these specific components:

• Title: An H1 heading (# <Title>) identifying the lesson.

• Hook: A blockquote (> <One-line hook>) providing a compelling subtitle.

• Type: Categorized as Learn, Build, or Reference.

• Languages: Comma-separated list matching the main.* files in the lesson's code/ directory.

• Prerequisites: Comma-separated list of upstream lesson names or "None".

• Time: Approximate duration prefixed with a tilde (e.g., ~30 minutes).

• Learning Objectives: An H2 section (## Learning Objectives) followed by 4-6 bullet points starting with action verbs.

Frontmatter Template Syntax

Here is the exact template enforced by the repository's Lesson contract in AGENTS.md:

# <Title>

> <One-line hook>

**Type:** <Learn | Build | Reference>
**Languages:** <comma-list matching the main.* files in code/>
**Prerequisites:** <comma-list of upstream lessons, or "None">
**Time:** ~<estimate in minutes>

## Learning Objectives

- <4-6 bullet points starting with a verb>

Concrete Example from the Curriculum

For a lesson located at phases/11-llm-engineering/01-prompt-engineering/docs/en.md, the frontmatter appears as:

# Prompt Engineering

> Master the art of crafting effective prompts for large language models.

**Type:** Learn
**Languages:** Python
**Prerequisites:** None
**Time:** ~30 minutes

## Learning Objectives

- Explain why prompt phrasing impacts model output.
- Identify common prompt patterns and pitfalls.
- Design prompts that elicit desired behavior.
- Evaluate prompt effectiveness with quantitative metrics.

Validation and Enforcement

The repository enforces this schema through multiple mechanisms:

1. AGENTS.md: Contains the canonical Lesson contract defining the frontmatter specification.
2. scripts/audit_lessons.py: A CI script that validates every lesson's docs/en.md for frontmatter compliance before merging.
3. site/build.js: Reads the frontmatter from each docs/en.md to generate the site's site/data.js and render lesson cards.

Summary

• The docs/en.md file requires a strict seven-field frontmatter template.
• Type must be one of Learn, Build, or Reference.
• Languages must correspond to actual files in the lesson's code/ directory.
• CI scripts validate compliance via scripts/audit_lessons.py.
• Site generation depends on consistent frontmatter parsing in site/build.js.

Frequently Asked Questions

What happens if a lesson is missing required frontmatter fields?

The CI pipeline fails. The scripts/audit_lessons.py script runs automated checks against every lesson's docs/en.md file, rejecting any pull requests that deviate from the schema defined in AGENTS.md.

How do I specify multiple languages in the frontmatter?

List them as a comma-separated value in the Languages field, ensuring each language matches a corresponding main.* file in the lesson's code/ directory. For example: **Languages:** Python, JavaScript.

Where is the frontmatter format defined in the repository?

The canonical specification resides in the Lesson contract section of AGENTS.md at the repository root. This document serves as the source of truth for the entire 435-lesson curriculum.

How does the site generator use the frontmatter data?

The site/build.js script parses each lesson's docs/en.md to extract metadata, populating site/data.js with lesson titles, time estimates, prerequisites, and learning objectives to build the curriculum navigation and lesson pages.

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