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

> Discover frontmatter requirements for docs/en.md files in AI Engineering From Scratch. Learn essential fields like title, hook, and objectives for automatic cataloging and navigation.

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

---

**Every [`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 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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)](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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), the validator checks each [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) for compliance with the frontmatter schema. Non-compliant files trigger CI failures.

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses the frontmatter to generate navigation links and populate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md):

```markdown

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) specification.

## Common Compliance Checks

When authoring [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) exists, list `python`).
- **Objective Count**: Include exactly 4-6 learning objectives; fewer or more will fail validation in [`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py).
- **Verb Form**: Start every learning objective with an action verb to maintain instructional clarity.

## Summary

- **Every [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py), which checks compliance against the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) contract.
- **The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script** consumes this frontmatter to generate navigation and populate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/main.py) and [`main.ts`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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)](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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py).

### How does the frontmatter affect site navigation?

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script parses the frontmatter from each [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md) file to generate the website’s navigation structure and populate [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js). The metadata drives the lesson tables, prerequisite chains, and language filters displayed on the curriculum site.