# How Mermaid Diagrams Replace ASCII Art in the AI Engineering Curriculum

> Learn how Mermaid diagrams replace ASCII art in AI engineering education. Discover scalable, accessible vector graphics for consistent lesson rendering across rohitg00/ai-engineering-from-scratch.

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

---

**The AI Engineering curriculum mandates Mermaid diagrams over ASCII art to ensure scalable, accessible vector graphics that render consistently across all 500+ lessons.**

The `rohitg00/ai-engineering-from-scratch` repository enforces a strict visual-design policy that prohibits ASCII art in favor of Mermaid diagrams. This standardization ensures every diagram scales cleanly on mobile devices, supports dark mode, and integrates with the automated static site generator.

## The Policy: Mermaid or SVG Only

According to the repository's contribution guide in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (lines 42-44), contributors must use **Mermaid** or SVG for all diagrams. ASCII art box-drawing is explicitly prohibited. This rule applies to all 500+ lessons in the curriculum, ensuring visual consistency across the entire learning path.

The rationale centers on three core requirements:

- **Scalability**: Vector graphics render sharply at any zoom level, unlike fixed-width ASCII characters
- **Accessibility**: Screen readers can parse Mermaid diagrams, while ASCII art appears as unstructured text
- **Maintainability**: A single diagram language keeps lesson files clean and reviewable

## Automated Rendering Pipeline

The static site generator located in [`site/lesson.html`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/lesson.html) automatically discovers fenced code blocks marked with the `mermaid` language identifier. The system imports the Mermaid library from a CDN and initializes it with theme-aware configuration at lines 1650-1654:

```javascript
<script type="module">
  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
  mermaid.initialize({
    startOnLoad: false,
    theme: document.documentElement.getAttribute('data-theme') === 'light' ? 'default' : 'dark',
    /* …additional options… */
  });
  window._mermaidReady = mermaid;
</script>

```

When a lesson loads, the JavaScript replaces each `pre.mermaid` element with a rendered SVG via `window._mermaidReady.render()`. The rendered output wraps inside a `div.mermaid-render`, while a hidden `pre.mermaid-source` preserves the original diagram text for the "Expand" toolbar functionality.

## Theme-Aware Styling and Accessibility

The CSS in [`site/lesson.html`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/lesson.html) (lines 795-838) defines containers, toolbars, and modal behavior for diagram interaction:

```css
.mermaid-container { margin: 24px 0; display: flex; justify-content: center; }
.mermaid-btn { font-family: var(--font-mono); border: 1px solid var(--rule-soft); }
.mermaid-modal-overlay.open { display: flex; }

```

These styles enable **dark mode support** by switching themes dynamically based on the `data-theme` attribute. Users can expand diagrams into a centered modal (`#mermaidModalOverlay`) for full-size viewing, a feature impossible with static ASCII art.

## Real-World Implementation: Safety Gate Architecture

Lesson 87 ("End-to-End Safety Gate") demonstrates the policy in practice. The file at [`phases/19-capstone-projects/87-end-to-end-safety-gate/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/87-end-to-end-safety-gate/docs/en.md) (lines 22-32) contains a flowchart illustrating the safety gate pipeline:

```markdown

```mermaid
flowchart TB
  IN[user prompt] --> PG[pre‑gen: detector]
  PG -->|block on high| OUT1[refusal + trace]
  PG --> M[mock LLM]
  M -->|stream| DG[during‑gen: token filter]
  DG -->|terminate early| OUT2[partial + trace]
  DG -->|complete| POST[post‑gen: classifier + rules]
  POST --> AGG[aggregate]
  AGG --> OUT3[final action + trace]

```

```

This diagram renders as a scalable vector graphic with readable text at any device width, unlike equivalent ASCII art that would break on mobile screens or require horizontal scrolling.

## Summary

- **Policy enforcement**: [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 42-44 mandate Mermaid diagrams exclusively, banning ASCII art from the curriculum.
- **Automated conversion**: The site generator in [`site/lesson.html`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/lesson.html) (lines 1650-1654) automatically renders Mermaid blocks to SVG using the CDN-hosted library.
- **Responsive design**: CSS definitions at lines 795-838 provide containers, toolbars, and modal support for optimal viewing across devices.
- **Accessibility**: Vector graphics support screen readers, theme switching, and clean scaling impossible with character-based diagrams.

## Frequently Asked Questions

### Why does the AI Engineering curriculum ban ASCII art?

ASCII art does not scale to different screen sizes, cannot be styled for dark mode, and presents accessibility barriers for screen reader users. The curriculum requires professional, maintainable visual assets that render consistently across all 500+ lessons.

### How does the site generator recognize Mermaid diagrams?

The system scans lesson markdown files for fenced code blocks marked with the `mermaid` language identifier. When the lesson loads in the browser, JavaScript in [`site/lesson.html`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/lesson.html) converts these blocks to SVG using the Mermaid library initialized at lines 1650-1654.

### Can contributors still use SVG files instead of Mermaid code?

Yes. While Mermaid is the preferred format for diagrams in `rohitg00/ai-engineering-from-scratch`, the [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) policy explicitly permits SVG as an alternative. However, ASCII art remains prohibited under all circumstances.

### How does the dark mode feature work for Mermaid diagrams?

The initialization code checks the `data-theme` attribute on the document root element, passing either `'default'` or `'dark'` to the Mermaid constructor. This ensures diagrams automatically match the user's selected theme without manual intervention from lesson authors.