Mermaid Project IDE Tutorial: Build Local Diagram Projects for Semantic Design Patterns

BLUF

The Mermaid Project IDE is a simple browser workspace for making Mermaid diagrams. If you have used Lucidchart, PowerPoint, Visio, draw.io, or a whiteboard, think of this as a text-based diagram notebook: you write Mermaid text on one side and preview the diagram on the other.

Use it to collect related diagrams into projects, preview them while you work, and export them as .mmd files or a .zip bundle. Your work is saved in your browser for the deployed site, so you can come back later on the same browser and keep working.

The tool is free, open source, and released under CC0 1.0; no account signup is needed, and the app does not get or sell your data.

This tutorial focuses on using the deployed app at https://skreen5hot.github.io/mermaid/. Developer notes and source-file details are collected near the end.

Table of Contents

  1. The Problem This App Solves
  2. Run the App
  3. Understand the Workspace
  4. Create a Project
  5. Create and Preview a Diagram
  6. Use Split View for Realtime Review
  7. Manage Diagrams in a Project
  8. Import and Export Artifacts
  9. Worked Scenario: Fleet Readiness Semantic Pattern
  10. Example: Instance Relations, ABox and RBox
  11. Example: TBox, ABox, and RBox Assertions
  12. Example: Ontology Imports
  13. Architecture Notes
  14. Testing and Security Notes
  15. Frequently Asked Questions

The Problem This App Solves

Teams often need quick diagrams before the final model, report, or architecture document is ready. Those diagrams may start in meeting notes, slide decks, chat messages, or a shared whiteboard. The problem is that they are easy to lose and hard to reuse.

The Mermaid Project IDE gives those diagrams a small workspace:

  • Put related diagrams in one project.
  • Give each diagram a name.
  • Edit the Mermaid text and preview the picture.
  • Save diagrams in the browser.
  • Export one diagram as .mmd.
  • Export the whole project as a .zip.
  • Upload existing .mmd files when you want to bring prior work in.

For ontology and knowledge-graph work, this is useful for sketching relationships between people, equipment, processes, datasets, identifiers, classes, properties, and ontology imports. You do not need to start in an ontology editor just to have a useful diagram conversation.

Run the App

Open the deployed app in a browser:

https://skreen5hot.github.io/mermaid/

That is the recommended starting point for tutorial use.

The page title is Mermaid Syntax Viewer & Editor, and the visible header is Mermaid Project IDE.

Understand the Workspace

The screen has three main areas:

Region Purpose
Project sidebar Choose a project, choose a diagram, upload .mmd files, or download a project .zip.
Code view Write or edit the Mermaid text.
Diagram view See the diagram preview.

When you first open the app, it creates a Default Project and a starter diagram named generic. You can use those, rename your work, or create a new project.

Create a Project

Use a project like a folder. It can hold all diagrams for one topic.

  1. Choose the + button next to the project selector.
  2. Enter a project name, such as:
Fleet readiness semantic patterns
  1. Confirm the prompt.
  2. The project selector switches to the newly created project.

Simple project examples:

  • Person and role patterns
  • Equipment identifier patterns
  • Maintenance process diagrams
  • Ontology import maps
  • Competency question diagrams
  • Example relationship diagrams

Create and Preview a Diagram

  1. Choose New.
  2. Enter a diagram name, such as:
vehicle-depot-instance-relations
  1. The editor opens with default Mermaid source.
  2. Replace the text with your diagram.
  3. Choose Save.
  4. Choose Diagram or Render to inspect the rendered output.

Use short diagram names if you plan to share the files later. For example:

fleet-abox-rbox.mmd
fleet-tbox-abox-rbox.mmd
fleet-ontology-imports.mmd

Use Split View for Realtime Review

The Split button shows the text and the diagram side by side. This is often the easiest way to work: edit the text on the left, watch the picture update on the right.

In split view:

  • The left pane holds the Mermaid source.
  • The right pane holds the rendered diagram.
  • The split-view divider can be dragged.
  • Content changes are debounced and re-rendered automatically.
  • Syntax errors are shown in the diagram pane instead of breaking the page.

This is especially helpful when checking arrow direction. A reversed arrow can change the meaning of the diagram.

Manage Diagrams in a Project

The sidebar lists diagrams for the selected project. Each item includes a small thumbnail preview when Mermaid can render the source.

Common actions:

Action Use
New Create a new named diagram in the current project.
Save Save the current diagram in the browser.
Rename Change the active diagram name.
Delete Delete the active diagram from the current project.
Select a sidebar item Load another diagram into the editor and preview pane.

Deletion is permanent. Export important diagrams before clearing browser data or deleting a project.

Import and Export Artifacts

The app supports simple file exchange.

Artifact Import Export Notes
Single Mermaid diagram Upload .mmd through the sidebar Export .mmd from the editor toolbar Best for Git commits, issue attachments, or copying into Markdown docs.
Mermaid project bundle Upload multiple .mmd files Download .zip from the sidebar Best for moving a group of related diagrams between browsers or teammates.

Uploaded .mmd files become diagrams in the current project. The file name, minus .mmd, becomes the diagram name.

The rendered diagram is a preview, not an export format in the current UI. JSON-LD export is also not exposed in the current UI. Treat .mmd and .zip as the supported user-facing exchange formats.

Worked Scenario: Fleet Readiness Semantic Pattern

This tutorial uses a fleet readiness scenario because it touches several common ontology-development concerns:

  • Persons and roles.
  • Vehicles and equipment.
  • Facilities and depots.
  • Processes and scheduled service.
  • Parts and inventory.
  • Identifier codes.
  • Information artifacts that designate real-world entities.

The modeling question is:

Which vehicles are at risk of missing scheduled service because required parts are unavailable at their assigned depot?

Create a project named:

Fleet readiness semantic patterns

Then create three diagrams:

  1. fleet-abox-rbox
  2. fleet-tbox-abox-rbox
  3. fleet-ontology-imports

The next sections provide Mermaid source for each diagram.

Example: Instance Relations, ABox and RBox

An ABox contains assertions about individuals. An RBox contains assertions about properties and relationships. In a diagram, the most useful first pass is often an instance graph: concrete objects connected by named relationships.

Paste this into a diagram named fleet-abox-rbox:

graph TD
    rdfInstance1["Label: Information System<br>Type: Information Processing Artifact<br>IRI: https://www.commoncoreontologies.org/ont00000117_InformationSystem"]
    rdfInstance2["Label: Vehicle Dataset<br>Type: Information Content Entity<br>IRI: https://www.commoncoreontologies.org/ont00000958_VehicleDataSet"]
    rdfInstance3["Label: Employee Dataset<br>Type: Information Content Entity<br>IRI: https://www.commoncoreontologies.org/ont00000958_EmployeeDataSet"]
    rdfInstance4["Label: Barry Guarino<br>Type: Person<br>IRI: https://www.commoncoreontologies.org/ont00001262_Person_BarryGuarino"]
    rdfInstance5["Label: Truck<br>Type: Truck<br>IRI: https://www.commoncoreontologies.org/ont00000606_Truck_FordF150"]
    rdfInstance6["Label: Act of Using Ford F150<br>Type: Act of Vehicle Use<br>IRI: https://www.commoncoreontologies.org/ont00000515_ActOfVehicleUse"]

    rdfInstance1 -- "is carrier of" --> rdfInstance2
    rdfInstance1 -- "is carrier of" --> rdfInstance3
    rdfInstance2 -- "is about" --> rdfInstance4
    rdfInstance3 -- "is about" --> rdfInstance5
    rdfInstance4 -- "uses" --> rdfInstance5
    rdfInstance4 -- "agent in" --> rdfInstance6
    rdfInstance6 -- "participates in" --> rdfInstance5

Review questions:

  • Are edge labels relationship names or informal English?
  • Does each edge direction match the intended predicate direction?
  • Are datasets represented as information content entities rather than as the vehicles or employees they describe?
  • Does the information system function as a carrier for the datasets?
  • Do the "is about" edges connect information content to the entities it represents?

The starting sample graph BT; is a valid direction declaration, but it is only a blank graph. For review work, add nodes and edges like the example above.

Example: TBox, ABox, and RBox Assertions

A TBox contains class-level assertions. An ABox contains individual-level assertions. An RBox contains relationship-level assertions such as subproperty, inverse, domain, or range patterns.

Paste this into a diagram named fleet-tbox-abox-rbox:

graph TD
    subgraph TBox["TBox: classes"]
        Vehicle["Vehicle"]
        Depot["Depot"]
        Part["Part"]
        ServiceProcess["Scheduled Service Process"]
        Identifier["Identifier"]
        Person["Person"]
        Role["Role"]
        Equipment["Equipment"]
        Process["Process"]
        Vehicle -->|subClassOf| Equipment
        ServiceProcess -->|subClassOf| Process
    end

    subgraph RBox["RBox: properties"]
        assignedToDepot["assignedToDepot"]
        hasAssignedVehicle["hasAssignedVehicle"]
        requiresPart["requiresPart"]
        participatesIn["participatesIn"]
        designates["designates"]
        assignedToDepot -->|inverseOf| hasAssignedVehicle
        assignedToDepot -->|domain| Vehicle
        assignedToDepot -->|range| Depot
        requiresPart -->|domain| ServiceProcess
        requiresPart -->|range| Part
        designates -->|range| Equipment
    end

    subgraph ABox["ABox: individuals"]
        vehicle17["vehicle-17"]
        depotEast["depot-east"]
        service883["service-883"]
        partA12["part-A12"]
        vin042788["vin-042788"]
        vehicle17 -->|rdf:type| Vehicle
        depotEast -->|rdf:type| Depot
        service883 -->|rdf:type| ServiceProcess
        partA12 -->|rdf:type| Part
        vin042788 -->|rdf:type| Identifier
        vehicle17 -->|assignedToDepot| depotEast
        service883 -->|requiresPart| partA12
        vin042788 -->|designates| vehicle17
    end

Use this kind of diagram to check whether a semantic design pattern has enough structure to support RDF data, SPARQL queries, and inference expectations.

Example: Ontology Imports

Ontology import diagrams show dependency structure. They are useful during release planning because imports can explain why a term is available, why a reasoner sees a relationship, or why a downstream application has a dependency on a large ontology module.

Paste this into a diagram named fleet-ontology-imports. This version keeps the structure and styling of the example while using Mermaid-valid node declarations:

flowchart TD
    n1["Common Core<br>Ontologies (CCO 2.0)"]
    n2["Basic Formal Ontology<br>(ISO 21838-2)"]
    n3["CCO-aligned Document Acts Ontology"]
    n4["Information Artifact Ontology (IAO)"]
    n5["Document Acts Ontology (D-Acts)"]

    n1 -- "imports" --> n2
    n3 ---|"imports"| n1
    n1 --- n4
    n4 ---|"imported by ontology"| n5
    n5 ---|"has derivative ontology"| n3

    style n3 color:#000000,fill:#5CE1E6
    style n2 color:#FFFFFF,fill:#737373
    style n5 color:#FFFFFF,fill:#737373
    style n4 color:#FFFFFF,fill:#737373
    style n1 color:#FFFFFF,fill:#737373

Review questions:

  • Which imports are required for reasoning and which are only used for annotation?
  • Can a smaller import set support the application pattern?
  • Are the imported ontologies stable enough for the release workflow?
  • Does the project need an import closure diagram for build or CI review?

Architecture Notes

For developers, the source repository is:

https://github.com/skreen5hot/mermaid

Local Development

For normal tutorial use, you can skip local setup. Use the deployed app.

For local development or offline review, run the app from a local web server instead of opening index.html directly from the filesystem.

From the ./mermaid directory:

npx serve

Then open the local URL shown by the command, commonly:

http://localhost:3000

In VS Code, you can also use Live Server:

  1. Open the mermaid folder.
  2. Right-click index.html.
  3. Choose Open with Live Server.

The main implementation files are:

File Role
index.html Browser entry point and application shell.
src/synchronizations.js Event wiring between independent concepts.
src/concepts/projectConcept.js Project list and current-project state.
src/concepts/diagramConcept.js Diagram list, current diagram, saving, deletion, renaming, and .mmd export.
src/concepts/storageConcept.js IndexedDB persistence for projects and diagrams.
src/concepts/uiConcept.js DOM rendering, split view, Mermaid preview, downloads, thumbnails, modals, and button state.

The app stores browser-local data in an IndexedDB database named:

mermaid_viewer_db

It uses two object stores:

Store Purpose
projects Project records with generated numeric IDs and names.
diagrams Diagram records with generated numeric IDs, project IDs, names, content, and modification dates.

The app follows a Concepts and Synchronizations architecture. Each concept owns its state and exposes actions through a listen(event, payload) interface. Cross-concept behavior is centralized in src/synchronizations.js.

flowchart TD
    HTML["index.html<br/>loads Mermaid, JSZip, and initializeApp()"]
    Sync["synchronizations.js<br/>wires concept events"]
    Project["projectConcept<br/>projects and currentProjectId"]
    Diagram["diagramConcept<br/>diagrams and currentDiagram"]
    Storage["storageConcept<br/>IndexedDB mermaid_viewer_db"]
    UI["uiConcept<br/>DOM, editor, preview, downloads"]

    HTML --> Sync
    Sync <--> Project
    Sync <--> Diagram
    Sync <--> Storage
    Sync <--> UI
    Project -->|do:listProjects / do:createProject| Storage
    Diagram -->|do:saveDiagram / do:loadDiagram| Storage
    Storage -->|projectsListed / diagramsListed| Sync
    UI -->|ui events| Sync
    Diagram -->|content changed| UI

This keeps the main behavior legible:

  • Storage does not manipulate the DOM.
  • UI does not directly write IndexedDB records.
  • Project state does not directly import diagram state.
  • Synchronizations make the event flow explicit.

The top-level app.js file currently exists but is empty. The active browser entry point is the inline module in index.html, which imports initializeApp() from src/synchronizations.js.

Testing and Security Notes

The project documentation emphasizes process-isolated testing, minimal dependencies, and explicit UI behavior.

Testing guidance:

  • Run the test suite from the ./mermaid directory with the package test command.
  • Test files are process-isolated so state does not leak between files.
  • Concepts should be tested through their public state, actions, and emitted events.
  • Synchronization tests should verify that event rules trigger the intended concept actions.
  • UI tests should prefer deterministic selectors and explicit waits.

Security guidance:

  • Treat diagram names and Mermaid source as user input.
  • Prefer textContent for dynamic text in the DOM.
  • When HTML insertion is required for rendered preview output or error display, keep escaping and containment behavior explicit.
  • Do not store passwords, tokens, or other secrets in IndexedDB.
  • Keep dependency use minimal and run npm audit as part of routine maintenance.

Frequently Asked Questions

Is the Mermaid Project IDE an ontology editor?

No. It is a diagram workspace. Use it to draft and review semantic patterns, relationship directions, import maps, process diagrams, and evidence diagrams that support ontology work.

Where is my data stored?

Projects and diagrams are stored in IndexedDB under the browser origin where the app is served. If you run the app at a different local URL or clear browser site data, you may see a different workspace or lose local data.

Is the app free and open source?

Yes. The repository owner has adopted the CC0 1.0 Universal license for this tool, which means it is intended to be freely reusable with no account signup or license fee.

The deployed app is a static web page. It stores project data in your browser for that site origin and does not require a backend account, so there is no app service receiving your diagrams to sell them.

How should a team share diagrams?

Export .mmd files or download the project .zip. Commit the files to a repository, attach them to issue tickets, or include them in ontology-review packages.

Why use split view?

Split view makes syntax and meaning visible at the same time. For semantic diagrams, this is useful because reviewers can catch reversed predicates, missing type assertions, disconnected nodes, and ambiguous relationship labels while the source is still easy to edit.

Can I render diagrams inside OntoEagle tutorials?

Yes. OntoEagle tutorials load Mermaid support through MkDocs configuration, so fenced mermaid code blocks can render in the generated tutorial site.

What should I export as the authoritative artifact?

Use .mmd as the authoritative source. Rendered diagrams are useful for review, but the Mermaid source is the artifact that can be diffed, versioned, edited, and regenerated.