Frontmatter Requirements for docs/en.md Files in AI Engineering From Scratch

Every docs/en.md file must begin with a standardized frontmatter block containing a title, hook, type, languages, prerequisites, time estimate, and learning objectives to ensure the curriculum tooling can automatically catalogue lessons and generate site navigation.

The docs/en.md files serve as the primary lesson explainer for each of the 435 lessons in the ai-engineering-from-scratch repository. These documents require a strict frontmatter schema that enables automated CI checks, consistent metadata across the curriculum, and dynamic site generation according to the [AGENTS.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) contract.

Required Frontmatter Fields for docs/en.md

The frontmatter block must appear at the very top of the file and contain exactly the following fields in this specific order.

Title and Hook

The document must start with an H1 title (# <Title>) followed immediately by a blockquote hook (> <One-line hook>). The hook should capture the lesson’s purpose in a single concise sentence.

Metadata Tags

Four mandatory bold-label fields must follow the hook:

• **Type:** – Must be one of Learn, Build, or Reference
• **Languages:** – Comma-separated list of all programming languages that have a main.* file in the lesson’s code/ folder (e.g., python, typescript)
• **Prerequisites:** – Comma-separated list of upstream lesson IDs required before this lesson, or None
• **Time:** – Estimated completion time prefixed with ~ (e.g., ~15)

Learning Objectives Section

The frontmatter concludes with an ## Learning Objectives header followed by 4-6 bullet points. Each bullet must start with an imperative verb (e.g., “Implement”, “Explain”, “Compare”) and describe specific outcomes the learner will achieve.

Validation and Automation

The frontmatter schema is enforced by the repository’s CI tooling to maintain consistency across the 435-lesson curriculum.

According to the source code in scripts/audit_lessons.py, the validator checks each docs/en.md for compliance with the frontmatter schema. Non-compliant files trigger CI failures.

The site/build.js script parses the frontmatter to generate navigation links and populate site/data.js. This drives the lesson tables and navigation menus on the generated website. The **Languages:** field must match the actual main.* files present in the lesson’s code/ directory, as the build process cross-references these paths.

Complete Frontmatter Example for docs/en.md

Below is a minimal, valid frontmatter snippet that satisfies the contract when placed at the top of docs/en.md:

# Gradient Descent from Scratch

> Learn how to implement the classic optimization algorithm without external libraries.

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

## Learning Objectives

- Derive the gradient descent update rule from first principles.
- Implement a vectorized version in NumPy.
- Visualize convergence on a 2‑D quadratic bowl.
- Compare learning‑rate schedules and their effect on speed.

This example demonstrates the exact spacing, punctuation, and header levels required by the AGENTS.md specification.

Common Compliance Checks

When authoring docs/en.md files, ensure compliance with these specific rules:

• Field Order: The seven components (H1, hook, Type, Languages, Prerequisites, Time, Learning Objectives) must appear in the sequence shown above.
• Language Accuracy: The **Languages:** value must exactly match the file extensions found in the lesson’s code/ directory (e.g., if main.py exists, list python).
• Objective Count: Include exactly 4-6 learning objectives; fewer or more will fail validation in scripts/audit_lessons.py.
• Verb Form: Start every learning objective with an action verb to maintain instructional clarity.

Summary

• Every docs/en.md file in the ai-engineering-from-scratch repository must begin with a standardized frontmatter block containing seven specific components.
• The frontmatter includes an H1 title, blockquote hook, Type, Languages, Prerequisites, Time estimate, and a Learning Objectives section with 4-6 imperative bullets.
• Validation occurs through scripts/audit_lessons.py, which checks compliance against the AGENTS.md contract.
• The site/build.js script consumes this frontmatter to generate navigation and populate site/data.js for the curriculum website.

Frequently Asked Questions

What happens if I omit the frontmatter in docs/en.md?

Omitting the frontmatter causes the scripts/audit_lessons.py CI validator to fail, blocking the pull request. The curriculum tooling requires this metadata to catalogue lessons, generate the site navigation, and enforce consistency across the 435-lesson curriculum.

How do I determine the correct value for the Languages field?

The **Languages:** field must match the actual main.* files present in the lesson’s code/ directory. For example, if the directory contains main.py and main.ts, you must list python, typescript. This cross-reference is verified during the CI audit process.

Where is the frontmatter schema formally defined?

The frontmatter contract is formally defined in the repository’s [AGENTS.md](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) file. This document specifies the hard rules for contributors, including the exact order of fields, formatting requirements, and validation logic implemented in scripts/audit_lessons.py.

How does the frontmatter affect site navigation?

The site/build.js script parses the frontmatter from each docs/en.md file to generate the website’s navigation structure and populate site/data.js. The metadata drives the lesson tables, prerequisite chains, and language filters displayed on the curriculum site.

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