# How Mermaid and SVG Diagrams Are Rendered in AI-Engineering-From-Scratch Lesson Documentation > Learn how Mermaid and SVG diagrams render in AI lesson documentation. Discover how Markdown code blocks transform into SVGs client-side using Mermaid JS. - Repository: [Rohit Ghumare/ai-engineering-from-scratch](https://github.com/rohitg00/ai-engineering-from-scratch) - Tags: internals - Published: 2026-06-13 --- **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/-/-/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`: ```markdown ```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 `
` 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


```

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 `
` 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:

```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 `` 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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/site/build.js) script treats Mermaid blocks as plain text, compiling them into [`site/data.js`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/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.