# What Diagram Types Are Permitted Under the Mermaid-Only Visual Convention?

> Discover allowed diagram types in Mermaid-only documentation. Learn about supported Mermaid library formats and SVG linking while avoiding ASCII art and Unicode graphics.

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

---

**The curriculum permits any diagram type supported by the Mermaid library or properly linked SVG files, while explicitly banning ASCII art and Unicode box-drawing graphics.**

The `rohitg00/ai-engineering-from-scratch` repository enforces strict documentation standards defined in **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)**. According to the **Hard rules** section (lines 47-48), all diagrams must be rendered as **Mermaid** code blocks or **SVG** images to ensure machine-readability and consistent cross-platform rendering.

## The Core Policy: Mermaid or SVG Only

The definitive rule resides in **[`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md)** at the repository root. This policy explicitly forbids ASCII or Unicode box-drawing graphics, mandating that contributors use only Mermaid syntax or standalone SVG files for visual documentation.

Because the policy references *Mermaid* without restricting diagram categories, any diagram family supported by the Mermaid parser is valid. This open-ended definition automatically includes existing types like flowcharts and sequence diagrams, as well as future diagram families added to the Mermaid specification.

## Supported Mermaid Diagram Types

The curriculum accepts all standard Mermaid diagram families. The most common types used in technical documentation include:

- **flowchart**: Visualizes process flows, decision trees, and system architectures
- **sequenceDiagram**: Illustrates interaction ordering between components, APIs, and databases
- **classDiagram**: Maps object-oriented relationships, inheritance hierarchies, and class structures
- **stateDiagram**: Represents finite-state machines, state transitions, and behavioral logic
- **gantt**: Displays project timelines, task schedules, and milestone tracking
- **erDiagram**: Models entity-relationship structures for database design
- **journey**: Tracks user experience paths, touchpoints, and satisfaction scores
- **mindmap**: Shows hierarchical brainstorming, concept relationships, and knowledge organization
- **pie**: Renders simple proportional data and percentage distributions

## Embedding Syntax and Examples

All Mermaid diagrams must be embedded using fenced code blocks with the `mermaid` language specifier. SVG images require standard Markdown image links pointing to `.svg` files.

### Mermaid Flowchart

```mermaid
flowchart TD
    A[Start] --> B{Is data valid?}
    B -- Yes --> C[Process data]
    B -- No --> D[Reject request]
    C --> E[End]

```

### Mermaid Sequence Diagram

```mermaid
sequenceDiagram
    participant User
    participant API
    participant DB
    User->>API: Send request
    API->>DB: Query
    DB-->>API: Result
    API-->>User: Response

```

### Mermaid Class Diagram

```mermaid
classDiagram
    class Animal {
        +String name
        +int age
        +makeSound()
    }
    class Dog {
        +String breed
        +bark()
    }
    Animal <|-- Dog

```

### Mermaid Gantt Chart

```mermaid
gantt
    title Project Schedule
    dateFormat  YYYY-MM-DD
    section Development
    Feature A       :a1, 2024-01-01, 10d
    Feature B       :after a1, 7d
    section Testing
    Unit Tests      :2024-01-12, 5d
    Integration     :2024-01-17, 4d

```

### SVG Image Reference

For diagrams created outside Mermaid, use standard Markdown image syntax linking to SVG files:

```markdown
![Architecture Overview](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/84-refusal-evaluation/docs/architecture.svg)

```

Formats like **PNG** or **JPG** are explicitly **not permitted** under the curriculum's visual policy.

## Prohibited Diagram Formats

The **Hard rules** section in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) explicitly bans ASCII art and Unicode box-drawing graphics. Contributors cannot use text-based diagrams created with characters like `|`, `-`, `+`, or box-drawing Unicode symbols. All visual elements must render through Mermaid's parser or as vector SVG graphics.

Real-world compliance appears in files like [`phases/19-capstone-projects/84-refusal-evaluation/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/84-refusal-evaluation/docs/en.md), which demonstrates proper Mermaid integration within lesson documentation.

## Summary

- **Mermaid diagrams** of any supported type (flowchart, sequence, class, etc.) are permitted when wrapped in ` ```mermaid ` code blocks.
- **SVG files** are the only acceptable external image format, referenced via standard Markdown image syntax.
- **ASCII and Unicode box drawings** are explicitly forbidden under the Hard rules in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md).
- All diagram syntax must be machine-parseable to maintain documentation consistency across the `rohitg00/ai-engineering-from-scratch` curriculum.

## Frequently Asked Questions

### Can I use PNG or JPG images for diagrams in the documentation?

No. The Mermaid-only visual convention explicitly restricts external images to **SVG format only**. Raster formats like PNG or JPG violate the policy defined in [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md). If you cannot express a diagram in Mermaid syntax, you must create it as an SVG file and link it using standard Markdown image syntax.

### Are there limitations on which Mermaid diagram types I can use?

No limitations exist. Because the policy states "Mermaid" without specifying diagram families, **any diagram type** supported by the Mermaid library is permitted. This includes flowcharts, sequence diagrams, Gantt charts, entity-relationship diagrams, user journeys, mindmaps, and any future diagram types added to the Mermaid specification.

### How do I verify my diagrams comply with the repository standards?

Check that your documentation uses either fenced code blocks tagged with `mermaid` for inline diagrams or standard Markdown image links pointing to files with the `.svg` extension. Ensure you have not used ASCII art or Unicode box-drawing characters to create visual elements. Reference [`AGENTS.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/AGENTS.md) lines 47-48 for the authoritative hard rule, and inspect [`phases/19-capstone-projects/84-refusal-evaluation/docs/en.md`](https://github.com/rohitg00/ai-engineering-from-scratch/blob/main/phases/19-capstone-projects/84-refusal-evaluation/docs/en.md) for compliant examples.

### What should I do if Mermaid cannot render my specific visualization?

Create your diagram using vector graphics software and export it as an **SVG file**. Place the file in the appropriate `docs/` or `outputs/` directory and reference it with Markdown image syntax like `![Description](path/to/diagram.svg)`. This approach satisfies the "Mermaid or SVG only" requirement while accommodating complex visualizations beyond Mermaid's native capabilities.