Mermaid Diagram Conventions in the AI Engineering Curriculum: Standards for Consistent Documentation

The rohitg00/ai-engineering-from-scratch curriculum enforces strict Mermaid diagram conventions requiring fenced code blocks with explicit mermaid language tags, SVG-based rendering via the mmdc CLI tool with automatic web-pointer fallback, and a complete prohibition of ASCII art or Unicode box-drawing characters.

The educational materials in the ai-engineering-from-scratch repository rely heavily on visual diagrams to explain complex AI engineering concepts. To ensure reproducibility and visual consistency across all lessons, the maintainers have established hard-coded rules within repository configuration files that govern exactly how diagrams must be authored and rendered.

Core Mermaid Diagram Requirements

The curriculum defines four non-negotiable rules for diagram creation, codified in the hard-rules section of AGENTS.md (lines 45-48) and the rendering notes in book/README.md (lines 30-35).

Language-Tagged Fenced Code Blocks

Every Mermaid diagram must be wrapped in a fenced code block that explicitly declares the language as mermaid. This tagging convention ensures that automated tooling can discover and process diagram blocks for SVG conversion. Undeclared or ambiguously tagged blocks will not render correctly in the curriculum's publishing pipeline.

Correct syntax:

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E

**Incorrect syntax (missing language tag):**

```markdown

graph TD A --> B

SVG-First Rendering Policy

The curriculum mandates that diagrams must be created with Mermaid syntax or provided directly as SVG files. This policy eliminates rendering inconsistencies across different operating systems and terminal emulators.

Rendering Pipeline and Tooling Configuration

According to book/README.md, the repository implements a dual-mode rendering strategy. When the command-line tool mmdc (Mermaid CLI) is available in the build environment, the system automatically converts Mermaid blocks to static SVG files. If mmdc is unavailable, the renderer falls back to generating a web-pointer, ensuring diagrams remain viewable even in minimal containerized environments.

This fallback mechanism guarantees that documentation remains accessible during local development, CI builds, and GitHub's native preview interfaces without requiring contributors to install the full Mermaid toolchain.

Prohibited Practices: ASCII and Unicode Box-Drawing

The hard-rules section in AGENTS.md explicitly bans diagrams that rely on ASCII art or Unicode box-drawing characters. These text-based visualization methods create inconsistent visual styles and frequently break on mobile devices or terminals with different character widths.

Prohibited syntax:

```text
+------+   +------+
| Start|->| End  |
+------+   +------+

Violations of this rule are flagged during automated CI checks, as they compromise the uniform visual quality required for professional educational materials.

## Real-World Implementation in Lesson Files

Throughout the curriculum, compliant Mermaid diagrams appear in lesson documentation files such as [`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). These files demonstrate the practical application of the conventions in complex technical explanations, ensuring that students encounter consistently formatted diagrams regardless of which lesson they are studying.

## Summary

- **Use only Mermaid or SVG**: The curriculum explicitly forbids ASCII art and Unicode box-drawing characters in favor of structured Mermaid syntax or pre-rendered SVG files.
- **Explicit language tagging**: All Mermaid diagrams must use fenced code blocks with the `mermaid` language specifier to enable automated tooling detection.
- **CLI rendering with fallback**: The `mmdc` tool converts diagrams to SVG when available; otherwise, the system generates web-pointers to maintain accessibility.
- **Repository-level enforcement**: The [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) hard-rules section (lines 45-48) and [`book/README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/book/README.md) rendering notes (lines 30-35) codify these standards for automated validation.

## Frequently Asked Questions

### What happens if I use a generic code block without the mermaid tag?

Generic code blocks lacking the `mermaid` language specifier will not be processed by the curriculum's automated rendering pipeline. According to the rules in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md), these blocks may be treated as plain text or flagged as formatting errors during CI validation.

### Can I use ASCII art diagrams for simple flowcharts?

No. The curriculum explicitly prohibits ASCII art and Unicode box-drawing characters under the hard-rules section. All diagrams must use proper Mermaid syntax wrapped in tagged code blocks or be provided as standalone SVG files to ensure consistent cross-platform rendering.

### Is the Mermaid CLI (mmdc) required to contribute diagrams?

While `mmdc` is not strictly required for contributions, it is the recommended toolchain. The rendering system in [`book/README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/book/README.md) implements a fallback mechanism that generates web-pointers when `mmdc` is unavailable, ensuring diagrams remain viewable without forcing contributors to install the CLI locally.

### Where are these conventions formally documented?

The conventions are formally documented in two key locations: [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) (specifically lines 45-48 in the hard-rules section) defines the authoring standards, while [`book/README.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/book/README.md) (lines 30-35) details the technical rendering behavior and fallback mechanisms.

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