How Mermaid and SVG Diagrams Are Rendered in AI-Engineering-From-Scratch Lesson Documentation

Mermaid diagrams are written as fenced code blocks in lesson Markdown files and converted to scalable SVG graphics client-side by the Mermaid JS library, while pre-generated SVGs are embedded directly as data URIs.

The AI-Engineering-From-Scratch repository generates rich, interactive lesson documentation using a hybrid static-and-dynamic approach for diagram rendering. When authors need to visualize neural network architectures or data flows, they write Mermaid syntax directly in Markdown files rather than managing separate image assets. This workflow ensures that Mermaid and SVG diagrams rendered in AI lesson documentation remain version-controlled, resolution-independent, and accessible across all devices.

Where Diagrams Are Defined in the Source

Lesson Markdown Structure

Every lesson in the curriculum lives as a Markdown file under the path phases/<phase-id>-<slug>/<lesson-id>-<slug>/docs/en.md. This convention keeps documentation colocated with lesson metadata, making it easy for contributors to find and edit content. When a diagram is needed, authors do not need to open image editing software; they simply add a fenced code block to the Markdown.

The Mermaid Code Block Syntax

To trigger diagram generation, authors wrap Mermaid syntax in a fenced code block starting with the literal word mermaid:

```mermaid
graph LR
  A[Input] --> B[Model]
  B --> C[Output]

The static site generator treats these blocks as plain text during the build phase, leaving the transformation to the browser. This approach decouples content authoring from asset compilation.

## The Build Pipeline

### Static Site Generation Process

The [`site/build.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script orchestrates the documentation build. It recursively reads all Markdown sources from the `phases/` directory, extracts the raw lesson content, and compiles them into a generated [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js) file. Critically, this script does not attempt to render Mermaid diagrams during the build; instead, it preserves the raw code blocks so that client-side JavaScript can handle the conversion.

### Preserving Mermaid Blocks for Client-Side Processing

By leaving Mermaid blocks untouched in [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/data.js), the architecture separates content from presentation. The generated data file exports lesson content as strings, which the front-end application loads and injects into the DOM. Only after the HTML is parsed does the Mermaid library scan for `<pre><code class="language-mermaid">` elements and perform the conversion.

## Client-Side Rendering Process

### Mermaid JS Library Initialization

The site’s HTML template includes the Mermaid library via CDN:

```html
<script src="https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js"></script>

A small initialization script runs on page load, calling mermaid.initialize({startOnLoad:true}). This configures the library to automatically scan the document and convert any detected Mermaid blocks.

DOM Transformation to SVG

When the page renders, the library executes the following steps:

1. Selects all <pre><code class="language-mermaid"> elements
2. Passes the text content to mermaid.render()
3. Replaces the original block with a self-contained SVG element using element.innerHTML = svgString

For example, a flowchart written in Markdown:

```mermaid
flowchart TD
    X[Input] -->|W₁| H[Hidden Layer]
    H -->|W₂| Y[Output]
    style X fill:#f9f,stroke:#333,stroke-width:2px
    style H fill:#bbf,stroke:#333,stroke-width:2px
    style Y fill:#bfb,stroke:#333,stroke-width:2px

Becomes a vector SVG element embedded directly in the DOM, complete with graphical nodes and styled connectors.

### Why SVG Output Matters

Mermaid’s `render()` method outputs an SVG string rather than a raster image. This design choice provides three key advantages:

- **Zero network overhead**: The diagram is rendered as part of the HTML, requiring no additional HTTP requests for image files
- **Resolution independence**: Vector graphics scale cleanly on high-DPI displays and mobile devices without pixelation
- **Accessibility**: The generated SVG includes a `<title>` element describing the diagram, which screen readers can announce to users

## Embedding Static SVG Assets

For diagrams that are generated outside the Mermaid workflow—such as custom icons or complex illustrations—the repository supports direct SVG embedding. Authors can include pre-generated SVGs as data URIs:

```markdown
<img src="data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIzMCIgaGVpZ2h0PSIzMCI+…"/>

The Markdown processor passes the <img> tag through unchanged, and the browser renders the inline vector graphic. Custom CSS in site/assets/ can style these elements to match the lesson theme.

Summary

• Lesson content resides in phases/<phase-id>-<slug>/<lesson-id>-<slug>/docs/en.md as standard Markdown
• Mermaid diagrams are authored as fenced code blocks and preserved raw through the site/build.js pipeline
• Client-side rendering converts Mermaid syntax to SVG using the CDN-hosted Mermaid JS library
• SVG output eliminates image requests, supports any screen resolution, and includes accessibility metadata
• Static SVG assets can be embedded directly via data URIs for icons and custom illustrations

Frequently Asked Questions

How does the build process handle Mermaid syntax?

The site/build.js script treats Mermaid blocks as plain text, compiling them into site/data.js without server-side rendering. The conversion to SVG happens entirely in the browser when the Mermaid library scans for <pre><code class="language-mermaid"> elements and calls mermaid.render().

Why does the documentation use SVG instead of PNG images?

SVG is a vector format that scales infinitely without quality loss, unlike raster PNGs. According to the AI-Engineering-From-Scratch source code, Mermaid’s render() method outputs an SVG string that is injected directly into the DOM via element.innerHTML, eliminating network requests for image files and ensuring crisp rendering on high-DPI displays.

Can I style the generated diagrams with custom CSS?

Yes. Because the diagrams render as inline SVG elements within the page DOM, they can be targeted with CSS selectors. The repository includes custom styles in site/assets/ that control colors, fonts, and stroke widths, allowing the diagrams to match the lesson theme consistently.

What version of Mermaid does the project use?

The HTML template loads Mermaid version 10 from the CDN at https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.min.js, initialized with mermaid.initialize({startOnLoad:true}) to trigger automatic rendering when the page loads.

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