Skip to content

Mermaid Slides: Present Markdown Diagrams in the Browser

Mermaid stores a diagram as text inside Markdown. That works well for versioned documentation, but a diagram embedded in a long page can be too small for a meeting. Exporting screenshots adds another file that can drift from the source.

I created Mermaid-Slides.com to turn Mermaid blocks from a Markdown file into a browser-based slide deck. This post explains the local rendering pipeline, navigation controls, and privacy boundary without requiring a separate slide configuration.

Navigate this post

The Problem: Static Diagrams and Presentation Friction

Developers and system architects frequently embed Mermaid syntax inside Markdown documentation to maintain version-controlled diagrams alongside source code. While this text-based diagram approach works effectively for repository documentation, presenting complex architecture during sprint reviews or design discussions introduces operational friction. Traditional presentation tools require manually cropping screenshots or copy-pasting code into external graphics utilities.

---
title: "Static Diagram Presentation Workflow"
---
graph TD
    accTitle: Static diagram presentation workflow
    accDescr: A Mermaid diagram embedded in Markdown becomes static documentation and often requires a screenshot for a presentation.
    A["Markdown Document (.md)"] --> B["Embedded Mermaid Diagram"]
    B --> C["Static Documentation"]
    C -.-> D["Manual Screenshot Workaround"]
    D -.-> E["Loss of Interactivity & Scalability"]

Limitations of Screenshot-Based Slide Decks

Exporting Mermaid diagrams to rasterized images (such as PNG or JPEG) introduces fixed pixel boundaries that degrade when zoomed on high-resolution displays. Additionally, static images lose diagram sub-element highlights, interactive navigation, and text search capability during live technical presentations.

The Solution: Instant Interactive Slide Generation

Mermaid Slides parses Markdown in the browser and converts each detected Mermaid block into a full-screen slide. A reader can paste text or choose a .md file; no separate deck file or build command is required.

---
title: "Mermaid Slides Rendering Workflow"
---
graph TD
    accTitle: Mermaid Slides rendering workflow
    accDescr: Pasted or uploaded Markdown is parsed in the browser and turned into a full-screen slide deck with keyboard, touch, or mouse controls.
    A(["Markdown Source (.md)"]) -- "Paste or Upload" --> B{{"Mermaid Slides Engine"}}
    B -- "Client-Side Parsing" --> C(["Interactive Slide Deck"])
    C -- "Keyboard Controls" --> D["Fullscreen Presentation"]
    C -- "Touch / Click Navigation" --> D

The interface supports keyboard navigation (++left++ / ++right++), touch gestures, and mouse controls. Diagram rendering runs in the browser, so moving between already rendered slides does not require another server request.

Deployment Options and Workflow Integration

Mermaid Slides supports three deployment models tailored to different privacy requirements and infrastructure environments:

  1. Hosted web application: Open Mermaid-Slides.com in a modern browser. The application assets arrive over the network before local rendering begins.
  2. Downloaded package: Download the compiled HTML and JavaScript bundle from the latest GitHub release, then run it without the hosted service.
  3. Containerized Deployment: Run the application locally or across internal teams using Docker containers.

To spin up a local instance using Docker, execute the following commands in your terminal:

docker-deploy.sh
# Pull the latest release image from Docker Hub
docker pull kunalpathak13/mermaid-slides:latest

# Launch container on port 3000
docker run -d -p 3000:3000 --name mermaid-slides kunalpathak13/mermaid-slides:latest
Air-Gapped and Enterprise Security

Local deployment gives the organization control over hosting, but a container is not automatically air-gapped. Verify bundled assets, browser requests, container networking, and update sources against the organization's data-loss-prevention policy.

Open Source Architecture

The application is published under the permissive MIT license on GitHub at kanad13/mermaid-slides. Developers can inspect, customize, or extend the core parsing and rendering pipelines to fit custom corporate documentation workflows.

Under the Hood: Technical Architecture

Component Technology Stack

  • React 19 Framework
    Provides dynamic UI component rendering, state management, and slide layout transitions.

  • TypeScript Type Safety
    Enforces strict interfaces across custom hooks, diagram parser tokens, and viewport metrics.

  • Vite Build System
    Builds the production assets and supports hot module replacement during development.

  • Tailwind CSS Engine
    Powers responsive presentation utility styling, grid positioning, and fullscreen viewport bounds.

Modular Custom Hook Architecture

The core application logic is decoupled into specialized React hooks that isolate state management from diagram rendering:

---
title: "Application Hook Responsibilities"
---
graph LR
    accTitle: Application hook responsibilities
    accDescr: Seven React hooks separate diagram rendering, file handling, navigation, parsing, layout, and interface-state responsibilities.
    subgraph "Custom Hooks Ecosystem"
        A[useMermaid] --> B[Diagram Rendering]
        C[useFileHandler] --> D[File Operations]
        E[useViewerNavigation] --> F[Slide Navigation]
        G[useKeyboardNavigation] --> H[Keyboard Controls]
        I[useDiagramParser] --> J[Content Parsing]
        K[useLayoutCalculations] --> L[Responsive Layout]
        M[useAutoHide] --> N[UI State Management]
    end

The useDiagramParser hook identifies raw ``mermaid code blocks within Markdown input and converts them into discrete slide data structures. Next,useMermaidinvokes the bundled client-side engine to produce SVG elements, whileuseViewerNavigationanduseKeyboardNavigation` coordinate viewport transitions.

Client-Side Privacy Architecture

The reviewed application renders the selected Markdown in the browser rather than posting the document to an application server. The following sequence shows that application data flow:

---
title: "Local Diagram Rendering Sequence"
---
sequenceDiagram
    accTitle: Local diagram rendering sequence
    accDescr: The browser passes Markdown to the local React app, which asks its bundled Mermaid engine to render SVG without uploading the content.
    participant User as User / Presenter
    participant Browser as Web Browser
    participant LocalApp as React Application
    participant Engine as Bundled Mermaid Engine

    User->>Browser: Upload or Paste Markdown
    Browser->>LocalApp: Pass Raw String Input
    LocalApp->>Engine: Parse & Render SVG (In-Memory)
    Engine->>LocalApp: Return Scalable Vectors
    LocalApp->>Browser: Display Interactive Slide Deck

    Note over User,Engine: Application renders the document locally

Verify the deployed build

The reviewed build bundles its script dependencies and does not intentionally upload the selected Markdown. Treat privacy as a property to verify in source and browser network tools after each deployment; the browser, host, extensions, and future builds remain separate trust boundaries.

Performance limits

Rendering time depends on the diagram type, layout complexity, Mermaid version, browser, and device. A node count alone does not predict the result. Test the actual deck on the presentation device, especially diagrams with long labels or dense edges, and split a slide when the text becomes too small to read.

Feedback and Contributions

Community feedback, bug reports, and pull requests are welcome. Developers interested in extending parser capabilities or adding new slide transition animations can contribute directly on GitHub via the issue tracker.

Conclusion

Mermaid Slides keeps a diagram's Markdown as the source and adds a presentation view around it. The hosted, downloaded, and containerized options provide different deployment boundaries; none should be described as private or air-gapped without checking the actual build and network controls.

References and further reading

Open the complete reference catalog

Primary Sources