Importing and Exporting Mermaid and PlantUML Diagrams in Revelation
Mermaid and PlantUML are the two most widely adopted diagrams-as-code formats. Both let teams keep diagrams alongside their source code, review them in pull requests, and render them in tools such as GitHub, GitLab, Confluence, and Notion. They are an excellent way to capture a single diagram at a time, but they were never designed to hold the broader, validated, multi-view models that enterprise architecture work demands.
Revelation now provides full import and export support for both formats. You can take an existing Mermaid sequence diagram, a PlantUML C4 container view, an ArchiMate diagram, or a Mermaid ER diagram, bring it into Revelation as a typed, validated model, and export it back to the same format with the structure preserved. The aim is simple: you should not have to choose between the convenience of diagrams as code and the discipline of an enterprise architecture repository.
You can try it now: open the Revelation EA tool and choose File → Import from Mermaid / PlantUML or File → Export as Mermaid / PlantUML.
What's Supported
The migration layer covers the diagram kinds most teams use in practice. Sequence diagrams and C4 architecture diagrams are supported in both directions for both tools. Flowcharts and ER diagrams are supported for Mermaid. ArchiMate is supported for PlantUML, using the Archimate-PlantUML library.
| Model type | Mermaid | PlantUML | Notes |
|---|---|---|---|
| Sequence diagram | Yes | Yes | PlantUML is the better choice if you use the full range of lifeline types (boundary, control, entity, database) — they each render as a distinct shape. Mermaid only has actor and participant shapes. |
| Flowchart | Yes | — | Start and end nodes both render as circles in Mermaid; Revelation remembers which is which. |
| Entity-relationship | Yes | — | Crow's-foot cardinality is mapped to the closest equivalent. Entity attribute lists are preserved on round-trip. |
| C4 architecture | Yes | Yes | Context, container, and component views are supported using the standard Person, System, Container, and Boundary elements. |
| ArchiMate | — | Yes | Uses the Archimate-PlantUML library. Every ArchiMate element type — business, application, technology, motivation, implementation — has a direct equivalent. |
Round-trip fidelity: importing and exporting the same diagram preserves element identifiers, types, labels, and ordering. You can safely edit the exported source in another tool and re-import it. Where a target format cannot natively represent a Revelation type, Revelation stores the precise type in a structured comment so it survives the round-trip.
Mermaid Examples
The following examples are available for direct import. Each is also viewable as source.
Mermaid sequence diagram
A support escalation flow showing eight participants — customer, support portal, identity service, ticket service, work queue, support agent, billing system, and notification service — with twelve messages and an alt fragment for the known-issue branch.
Source: support-escalation-sequence.mmd
sequenceDiagram
actor User as Customer
participant Portal as Support Portal
participant Auth as Identity Service
User->>Portal: Open support request
Portal->>Auth: Validate session
Auth-->>Portal: Session validMermaid flowchart
An order fulfilment workflow with ten nodes — start and end markers, validation and reservation steps, decision diamonds for payment approval and stock availability, and a database node — connected by eleven labelled edges.
Source: order-fulfillment-flowchart.mmd
Mermaid entity-relationship diagram
A learning platform data model with eight entities — student, course, module, lesson, enrolment, submission, instructor, cohort — and eight relationships covering enrolment, instruction, and submission lifecycles.
Source: learning-platform-er.mmd
Mermaid C4 container diagram
An adaptation of the well-known C4-PlantUML "Big Bank plc" container sample, rendered in Mermaid's C4 dialect. Shows a customer interacting with web, single-page, and mobile applications, all served by a backend API that integrates with a database, an email system, and a mainframe banking system.
Source: internet-banking-container.mmd
PlantUML Examples
PlantUML sequence diagram
The same support escalation scenario as the Mermaid example, expressed in PlantUML. Because PlantUML has native lifeline primitives for boundary, control, entity, database, and queue, each participant renders as the shape architects expect rather than collapsing to a generic participant box.
Source: support-escalation-sequence.puml
@startuml
actor "Customer" as User
boundary "Support Portal" as Portal
control "Identity Service" as Auth
queue "Work Queue" as WorkQueue
entity "Billing System" as Billing
User ->> Portal : Open support request
@endumlC4-PlantUML container diagram
The Big Bank plc container view in C4-PlantUML, using the standard !include of the C4_Container stdlib. Identical structure to the Mermaid C4 example — useful for comparing the two notations side by side.
Source: internet-banking-container.puml
Archimate-PlantUML diagram
An online retail capability realisation expressed in ArchiMate. Includes business actors and roles, business processes and services, application components and data objects, and technology infrastructure — connected by triggering, assignment, serving, realisation, flow, and access relationships.
Source: online-retail-archimate.puml
@startuml
!include <archimate/Archimate>
Business_Actor(customer, "Customer")
Business_Process(order_journey, "Order Journey")
Application_Component(storefront, "Web Storefront")
Rel_Triggering_Right(customer, order_journey, "places order")
Rel_Realization_Right(storefront, order_service, "realizes")
@endumlHow to Use It
Importing
Open Revelation, choose File → Import from Mermaid / PlantUML, paste the source into the dialog, and choose Import. The source format is auto-detected from the first non-blank line. Imported models open with the layout most suited to the diagram kind — Sequence layout for sequence diagrams, Dynamic layout for everything else.
Exporting
With a model open, choose File → Export as Mermaid / PlantUML, pick a target format, and either copy the preview text or download it as a .mmd or .puml file. The dialog shows you which formats are valid for the current model type and warns if the model uses elements the target cannot represent.
Round-tripping
Both directions are designed so that import → export → import returns the same model. Elements that have no native representation in the target format are preserved through structured comments that the renderer ignores but Revelation reads back. The result is that you can edit the exported source in another tool, hand it back through the importer, and the resulting Revelation model will be functionally identical to where you started.
When to Choose Which Tool
Mermaid and PlantUML are complementary rather than competing. Use Mermaid when the priority is in-document rendering — GitHub READMEs, Notion pages, Confluence wikis — and the diagram kind is one Mermaid handles natively. Use PlantUML when you need the richer notation set (ArchiMate, true sequence lifeline types, the full C4-PlantUML toolkit) and you have a renderer in your stack — most commonly via Kroki or a PlantUML server.
Revelation sits behind both. You can take any diagram in either format, treat it as a starting point, evolve it into a properly structured architecture model with typed elements and persistent layouts, and export it back when you need to publish or share. The format is no longer a commitment.
Try It
Open the Revelation EA tool, choose File → Import from Mermaid / PlantUML, and paste one of the examples above — or one of your own diagrams.
All examples in this article are available under /app/reference/migration-examples/.