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

> Learn the required frontmatter structure for lesson markdown files in AI Engineering From Scratch. Ensure automated curriculum generation and consistent lesson discovery.

- Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch)
- Tags: documentation
- Published: 2026-08-26

---

**The `ai-engineering-from-scratch` repository enforces a strict frontmatter schema in [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/docs/en.md), this satisfies the repository's validation scripts:

```markdown

# 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** – The *Lesson contract* section specifies the exact schema requirements and field semantics.
- **[`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/LESSON_TEMPLATE.md)** – Provides a concrete, copy-pasteable template demonstrating proper field ordering and formatting.
- **[`scripts/audit_lessons.py`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/scripts/audit_lessons.py)** – The validation script that parses each [`docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) and [`LESSON_TEMPLATE.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.