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

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. 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 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

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

Mermaid Sequence Diagram

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

Mermaid Class Diagram

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

Mermaid Gantt Chart

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:

![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 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, 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.
• 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. 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 lines 47-48 for the authoritative hard rule, and inspect 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.

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