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

> Understand the lesson frontmatter format in docs/en.md for the AI Engineering curriculum. Learn about the seven required metadata fields that automate site generation and CI validation.

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

---

**Every lesson's [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md):

```markdown

# <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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/11-llm-engineering/01-prompt-engineering/docs/en.md), the frontmatter appears as:

```markdown

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) for frontmatter compliance before merging.
3. **site/build.js**: Reads the frontmatter from each [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) to generate the site's [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) and render lesson cards.

## Summary

- The [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py).
- Site generation depends on consistent frontmatter parsing in [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py) script runs automated checks against every lesson's [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file, rejecting any pull requests that deviate from the schema defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses each lesson's [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) to extract metadata, populating [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) with lesson titles, time estimates, prerequisites, and learning objectives to build the curriculum navigation and lesson pages.