What Is glossary/terms.md? How the AI Engineering Glossary Is Maintained

The glossary/terms.md file in the AI Engineering from Scratch repository is the canonical, alphabetically-organized glossary that serves as the single source of truth for all 435 curriculum lessons, maintained manually by contributors but validated and published automatically through the site/build.js pipeline.

This master terminology file lives at glossary/terms.md in the rohitg00/ai-engineering-from-scratch repository and enforces a strict three-bullet format for every entry. It ensures that technical terms appearing across the sprawling curriculum remain consistent, with misconceptions clarified and etymology preserved for learner reference.

Anatomy of the Glossary File

Each entry in glossary/terms.md follows a rigid structure designed for both human readability and programmatic parsing.

The Three-Bullet Format

Every term uses an H3 heading followed by exactly three bullet points:

### Term

- **What people say:** “common misconception”
- **What it actually means:** precise technical definition
- **Why it’s called that:** brief etymology or historical note

This pattern allows the build script to distinguish between colloquial misunderstandings and formal definitions while capturing the linguistic history of AI engineering terminology.

How the Glossary Is Maintained

The maintenance workflow combines manual curation with automated enforcement to prevent glossary drift across the curriculum.

Manual Contributions and Review Process

When a lesson introduces a concept that appears in multiple places, contributors must add the term to glossary/terms.md before committing the lesson. According to CONTRIBUTING.md, this step is mandatory to ensure the term exists in the single source of truth before it is referenced elsewhere.

The AGENTS.md file specifies that reviewers must verify:

1. The term follows the three-bullet format
2. The definition is actually reused across lessons
3. The entry is alphabetically positioned

Changes enter through standard pull requests and receive the same review scrutiny as code changes.

Automated Parsing and Site Generation

The site/build.js script reads glossary/terms.md and converts it into structured JSON for the live website. This guarantees that the published glossary at site/glossary.html always reflects the latest markdown.

The parser uses a simple regex-based extraction:

// site/build.js (excerpt)
const GLOSSARY_PATH = path.join(REPO_ROOT, 'glossary', 'terms.md');
const glossaryContent = fs.readFileSync(GLOSSARY_PATH, 'utf8');

function parseGlossary(md) {
  const entries = [];
  const lines = md.split('\n');
  let current = null;
  
  for (const line of lines) {
    const termMatch = line.match(/^###\s+(.*)$/);
    if (termMatch) {
      if (current) entries.push(current);
      current = { term: termMatch[1], items: [] };
      continue;
    }
    const bulletMatch = line.match(/^-\s+\*\*([^*]+)\*\*:\s+(.*)$/);
    if (bulletMatch && current) {
      current[bulletMatch[1].toLowerCase().replace(/\s+/g, '')] = bulletMatch[2];
    }
  }
  if (current) entries.push(current);
  return entries;
}

const glossary = parseGlossary(glossaryContent);
// Serialized into site/data.js for the live glossary page

This build-time generation ensures that any syntax error in the markdown immediately surfaces during the build process.

Continuous Integration Checks

The .github/workflows/curriculum.yml CI pipeline runs site/build.js on every push. If the glossary parsing fails—whether from a malformed heading or missing bullet—the CI job blocks the merge. This closed loop prevents broken glossary entries from reaching the main branch while allowing the curriculum to scale without terminology fragmentation.

Working with the Glossary

Adding a New Term

To add Retrieval-Augmented Generation (RAG) to the curriculum, a contributor would append this to glossary/terms.md:

### Retrieval‑Augmented Generation (RAG)

- **What people say:** “just another prompt trick”
- **What it actually means:** A two‑stage pipeline where a model first retrieves relevant documents from an external corpus, then conditions a language model on those documents to produce a grounded answer.
- **Why it’s called that:** The generation step is *augmented* by the retrieved knowledge.

After committing this change and opening a PR, the automated pipeline validates the format before the site generation proceeds.

Referencing Terms in Lessons

Lessons link directly to the glossary using relative markdown paths:

In the **Retrieval‑Augmented Generation** lesson we rely on the definition from the
glossary: see [Retrieval‑Augmented Generation (RAG)](../glossary/terms.md#retrieval‑augmented-generation-rag).

This creates bidirectional traceability between lesson content and canonical definitions.

Summary

• glossary/terms.md is the single source of truth for all 435 lessons in the AI Engineering from Scratch curriculum, located in the repository root.
• Three-bullet format: Every entry must include "What people say," "What it actually means," and "Why it's called that" to maintain consistency.
• Manual maintenance: Contributors add terms via pull requests, reviewed against CONTRIBUTING.md and AGENTS.md policies.
• Automated validation: The site/build.js script parses entries into JSON, and .github/workflows/curriculum.yml blocks merges with broken syntax.
• Live generation: The build pipeline converts markdown entries into the interactive glossary page, ensuring the website stays synchronized with the repository.

Frequently Asked Questions

How do I add a new term to the AI Engineering glossary?

Create a new H3 heading in glossary/terms.md following the three-bullet format (misconception, definition, etymology), then submit a pull request. The term must be alphabetically placed and the CI pipeline will validate that the markdown parses correctly before allowing the merge.

What happens if I forget to update the glossary before using a term in a lesson?

The CONTRIBUTING.md guidelines explicitly require that terms be added to glossary/terms.md before they are referenced in lessons. While the build won't fail on missing terms, reviewers will block the PR for violating the curriculum's single-source-of-truth policy for terminology.

Why does the glossary use the specific three-bullet format?

The format standardizes how terminology is documented across the curriculum and enables the automated parser in site/build.js to extract structured data. The regex in the build script specifically looks for bullet lines matching **Label:** to distinguish between misconceptions, technical definitions, and historical notes.

Can I link to specific terms from outside the repository?

Yes. The build system generates anchor IDs from the H3 headings (converting spaces to hyphens and lowercasing), so external links can target specific definitions using the pattern https://[site-url]/glossary.html#term-name after the JSON data is rendered on the live site.

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