Expected Frontmatter Structure for Lesson Markdown Files in AI Engineering From Scratch

The ai-engineering-from-scratch repository enforces a strict frontmatter schema in docs/en.md files that requires a level‑1 title, a one‑line hook, metadata fields (Type, Languages, Prerequisites, Time), and a Learning Objectives section to ensure automated curriculum generation and consistent lesson discovery.

Every lesson in the rohitg00/ai-engineering-from-scratch curriculum follows a standardized frontmatter structure defined in the Lesson contract section of AGENTS.md. This schema ensures that the site generator, CI pipelines, and curriculum dashboards can parse lesson metadata automatically.

Required Frontmatter Fields

Each lesson markdown file located at phases/<phase-slug>/<lesson-slug>/docs/en.md must contain exactly seven structural elements in the following order:

Title and Hook

The frontmatter opens with a standard markdown level‑1 heading followed immediately by a blockquoted tagline:

• # <Title> – The exact lesson title using a single H1 heading.

• > <One-line hook> – A concise, memorable description that appears in lesson cards.

Metadata Declarations

Four bold-labeled fields provide structured metadata for automation tools:

Field	Format	Purpose
Type	**Type:** Learn | Build | Reference	Categorizes lessons as theory (Learn), implementation (Build), or overview (Reference).
Languages	**Languages:** <comma-separated list>	Must match the main.* files present in the lesson's code/ directory; used by CI to verify code completeness.
Prerequisites	**Prerequisites:** <comma-separated list> | None	Specifies upstream lessons required before starting, or None for entry points.
Time	**Time:** ~<minutes> min	Provides the estimated completion duration for curriculum planning.

Learning Objectives Section

The frontmatter concludes with an H2 heading ## Learning Objectives followed by a bullet list containing 4–6 actionable items. Each objective must start with a verb (e.g., Implement, Explain, Compare) to clarify measurable outcomes.

Why the Frontmatter Structure Matters

Adhering to this schema provides three critical benefits for the curriculum ecosystem:

• Consistency – Uniform metadata allows the site generator to render navigation tables and lesson cards identically across all phases.
• Automation – The Languages field triggers validation in scripts/audit_lessons.py, which verifies that a corresponding main.* file exists for every listed language.
• Discoverability – Search indexes and curriculum dashboards use the Type, Prerequisites, and Time fields to filter and sort lessons dynamically.

Complete Frontmatter Example

Below is a minimal, fully compliant frontmatter block for a hypothetical lesson on "Self-Attention". When placed at the top of docs/en.md, this satisfies the repository's validation scripts:

# Self-Attention

> Compute attention weights without any library shortcuts

**Type:** Build  
**Languages:** Python, TypeScript  
**Prerequisites:** Phase 02 – Linear Algebra, Phase 04 – Matrix Multiplication  
**Time:** ~30 min

## Learning Objectives

- Derive the scaled-dot-product formula
- Implement a single-head attention layer from scratch
- Verify the implementation with unit tests
- Compare the custom implementation to a library version

Validation and Key Files

The frontmatter contract is defined and enforced across three primary locations:

• AGENTS.md – The Lesson contract section specifies the exact schema requirements and field semantics.
• LESSON_TEMPLATE.md – Provides a concrete, copy-pasteable template demonstrating proper field ordering and formatting.
• scripts/audit_lessons.py – The validation script that parses each docs/en.md file to ensure compliance before merging.

Summary

• Location: All lesson frontmatter lives in phases/<phase-slug>/<lesson-slug>/docs/en.md.
• Structure: Mandatory H1 title, blockquote hook, four bold metadata lines, and an H2 Learning Objectives section.
• Automation: The Languages field drives CI validation against main.* files in the code/ directory.
• Source of Truth: Schema definitions reside in AGENTS.md and LESSON_TEMPLATE.md at the repository root.

Frequently Asked Questions

Where exactly must the frontmatter be located in the repository?

The frontmatter must reside at the top of a file named docs/en.md inside each lesson directory, following the path pattern phases/<phase-slug>/<lesson-slug>/docs/en.md. This location is hardcoded into the site generator and validation tooling.

What happens if the Languages field does not match the code directory contents?

The CI pipeline running scripts/audit_lessons.py will fail the build. The script cross-references the comma-separated values in the Languages field against the main.* filenames present in the lesson's code/ folder, flagging any mismatches or missing implementations.

Can I use HTML tags or YAML delimiters instead of markdown headings for the frontmatter?

No. The schema strictly requires standard markdown ATX headings (# and ##), blockquotes (>), and bold text (**). YAML frontmatter delimiters (---) are not supported by the parser used in the curriculum website generator.

Is the Time field used for any automated scheduling or gating mechanisms?

Currently, the Time field serves as metadata for student planning and curriculum dashboards only. It does not trigger automated gating, but future roadmap items suggest using it for personalized learning path recommendations.

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