Frontmatter Schema for AI Engineering Lesson docs/en.md Files

The rohitg00/ai-engineering-from-scratch repository mandates that every lesson's docs/en.md file begin with a standardized YAML-style frontmatter block containing seven required metadata fields: Title, Hook, Type, Languages, Prerequisites, Time, and Learning Objectives.

The curriculum architecture depends on strict documentation standards to enable automated parsing and consistent learner onboarding. Each instructional unit stores its descriptive metadata in a docs/en.md file using a disciplined schema defined in AGENTS.md (lines 72‑84). Mastering this frontmatter structure ensures your lessons integrate seamlessly with the repository's build system and navigation logic.

Required Frontmatter Fields

The frontmatter schema requires seven specific metadata declarations appearing in a fixed sequence. Each field serves a distinct purpose in cataloging the lesson's content and dependencies.

Title

The Title field appears as a level-one markdown heading (# <Title>) at the very beginning of the file. This heading defines the lesson's display name in the curriculum navigation and should clearly indicate the subject matter.

Hook

Immediately following the title, the Hook field provides a one-line teaser using markdown blockquote syntax (> <One-line hook>). This description appears in lesson listings and search previews, concisely explaining what the learner will accomplish.

Type

The Type field categorizes the instructional approach using bold text syntax: **Type:** <Learn | Build | Reference>. Valid values are:

• Learn – Conceptual instruction and theory
• Build – Hands-on implementation projects
• Reference – Supplementary documentation and lookup tables

Languages

Specified as **Languages:** <comma-list>, this field must exactly match the main.* file extensions found in the lesson's code/ directory. For example, if code/main.py and code/main.ts exist, the frontmatter must declare **Languages:** python, typescript.

Prerequisites

The Prerequisites field uses the syntax **Prerequisites:** <comma-list | "None"> to declare dependency lessons that learners must complete first. Use comma-separated lesson identifiers (matching directory names) or explicitly state "None" for introductory topics.

Time

Estimated duration appears as **Time:** ~<estimate in minutes>, providing learners with scheduling expectations. The tilde prefix indicates approximation.

Learning Objectives

Following the metadata fields, a dedicated ## Learning Objectives section contains a bulleted list of 4–6 outcomes. Every bullet must begin with an action verb describing measurable skills the learner will acquire.

Complete Frontmatter Structure

According to the specification in AGENTS.md, the canonical template for docs/en.md follows this exact sequence:

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

This structure ensures the repository's automated agents can parse lesson metadata consistently across the curriculum hierarchy.

Implementation Examples

Real-world instances of this frontmatter schema appear throughout the phases/ directory structure. Here are two validated patterns from the source code:

Minimal Learn-Type Lesson

This example from the curriculum demonstrates a basic single-language lesson with no dependencies:

# Introduction to Neural Networks

> Learn the basics of neural network architecture.

**Type:** Learn
**Languages:** python
**Prerequisites:** None
**Time:** ~30

## Learning Objectives

- Explain what a neuron is
- Build a simple perceptron in Python
- Visualize training loss over epochs

Build-Type Lesson with Multiple Languages

Complex projects requiring prior knowledge use the extended format seen in advanced modules like phases/*/12-multi-head-attention/:

# Implement a Transformer from Scratch

> Hands-on construction of a full transformer model.

**Type:** Build
**Languages:** python, typescript
**Prerequisites:** 12-multi-head-attention, 08-linear-algebra
**Time:** ~120

## Learning Objectives

- Write the scaled-dot-product attention function
- Assemble multi-head attention layers
- Train the transformer on a toy dataset
- Evaluate model performance and fine-tune hyper-parameters

Source Files and Validation

The definitive schema specification resides in [AGENTS.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) at lines 72‑84. This file serves as the single source of truth for documentation standards.

Individual lesson implementations appear at paths like phases/01-intro-to-ml/01-linear-regression/docs/en.md, where the frontmatter schema is validated against the actual code/ directory contents. The repository's build system cross-references the Languages field against existing main.* files to prevent documentation drift.

Summary

• The docs/en.md frontmatter schema requires seven mandatory fields: Title, Hook, Type, Languages, Prerequisites, Time, and Learning Objectives.
• Type must be one of Learn, Build, or Reference.
• Languages must correspond exactly to file extensions in the lesson's code/ directory.
• Prerequisites use lesson directory identifiers or "None" for entry-level content.
• The complete specification is defined in AGENTS.md (lines 72‑84) and implemented across phases/*/*/docs/en.md files.

Frequently Asked Questions

What happens if the Prerequisites field is left empty?

The frontmatter schema requires an explicit value. If no prior lessons are required, you must write **Prerequisites:** None rather than leaving the field blank. Empty fields break the repository's automated parsing logic that builds the curriculum dependency graph.

Can I list languages in the frontmatter that don't exist in the code/ directory?

No. The Languages field must strictly match the main.* files present in the lesson's code/ directory. Mismatches between documented languages and actual source files trigger validation errors during the build process, as the schema enforces consistency between metadata and implementation.

How many learning objectives should a lesson include?

The schema specifies 4–6 bullet points under the ## Learning Objectives section. Each objective must start with an action verb (e.g., "Build," "Explain," "Evaluate"). Lists shorter than four items lack sufficient granularity, while exceeding six objectives suggests the lesson scope is too broad for a single unit.

Is the Time field strictly enforced for lesson completion?

The Time field provides an estimated duration prefixed with a tilde (~) to indicate approximation (e.g., ~45). While not enforced by automated tooling, maintaining realistic estimates helps learners schedule study sessions and curriculum planners balance workload distribution across phases.

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