kunalpathak13/mermaid-slides

Mermaid Slides

Turn Markdown files with Mermaid diagrams and images into a presentation-ready deck in seconds. Mermaid Slides keeps the source plain-text, renders everything locally, and lets you present the result in the browser, offline, or from Docker — ideal for architecture reviews, demos, and docs walkthroughs.

https://img.shields.io/badge/Live_Demo-blue?style=for-the-badge]([***] https://img.shields.io/badge/Docker_Image-blue?style=for-the-badge](https://hub.docker.com/r/kunalpathak13/mermaid-slides) https://img.shields.io/badge/VS_Code-Mermaid_Slideshow-purple?style=for-the-badge](https://marketplace.visualstudio.com/items?itemName=KunalPathak.mermaid-slideshow) https://img.shields.io/badge/VS_Code-Markdown_Presentation_Tool-7c3aed?style=for-the-badge](https://marketplace.visualstudio.com/items?itemName=KunalPathak.markdown-presentation-tool) https://img.shields.io/badge/Documentation-green?style=for-the-badge](docs/) https://img.shields.io/badge/Privacy_First-orange?style=for-the-badge](#-privacy--security)

!Mermaid Slides Demo

Quick Start

Online (Recommended)

Visit Mermaid Slides and start creating presentations immediately.

Docker Container

Run Mermaid Slides in a Docker container for easy deployment:

bash
# Pull and run the latest version
docker pull kunalpathak13/mermaid-slides:latest
docker run -p 3000:3000 kunalpathak13/mermaid-slides:latest

# Open browser to http://localhost:3000

• Container Ready: Multi-platform support (AMD64, ARM64)
• Isolated Environment: Complete containerized solution
• Easy Deployment: Perfect for corporate environments

Offline Package

Download the complete offline package for local use without internet dependency:

bash
# Download from GitHub Releases
# Visit: https://github.com/kanad13/mermaid-slides/releases/latest

# Extract and run:
unzip mermaid-slides-offline-v*.zip
cd mermaid-slides-offline

# Choose your preferred server:
python3 start-server.py  # Python option
node start-server.js     # Node.js option
./start-server.sh        # Auto-detect (macOS/Linux)
start-server.bat         # Auto-detect (Windows)

# Open browser to http://localhost:3000

Local Development

Requires Node 20.19+ or 22.12+ for local development and production builds (matches Vite 7 requirements).

bash
git clone https://github.com/kanad13/mermaid-slides.git
cd mermaid-slides
npm install
npm run dev

Thanks Mermaid.js Team!

Important Notice: This is an independent, community-driven project and is not an official product of the Mermaid.js team. Mermaid Slides (this project) is built with deep gratitude to the Mermaid.js creators and uses their library under the MIT License. All credit for the core diagramming functionality goes to the https://github.com/mermaid-js/mermaid.

Key Features

Presentation & Navigation

• File Handling - Drag & drop, file browser, or paste markdown content
• Mixed Content - Mermaid diagrams + images in unified presentations
• Title Extraction - Automatically extracts markdown headers as slide titles with user toggle
• Navigation - Keyboard controls, progress bar, grid view, thumbnails
• Settings Panel - Toggle title display and auto-hide behavior during a session
• Presentation Mode - Full-screen, distraction-free experience
• Responsive - Works on desktop, tablet, and mobile devices

Privacy & Security

• Zero Tracking - No analytics, telemetry, or data collection
• Offline First - Complete functionality without internet dependency
• Local Processing - All diagram rendering happens on your device
• Self-Contained - All distributions bundle dependencies locally
• Privacy Modals - Built-in privacy policy and legal notice information

Multi-Platform Availability

• Web App - Instant access via GitHub Pages
• Offline Package - Download and run locally on any OS
• Docker Container - Containerized deployment for any environment

Related VS Code Tools

If you prefer editor-native presentations, these companion tools are already live in the VS Code Marketplace:

Mermaid Slideshow

• Marketplace: https://marketplace.visualstudio.com/items?itemName=KunalPathak.mermaid-slideshow
• Best for: Mermaid-only files where each diagram becomes its own focused slide
• Highlights: Keyboard navigation, live preview updates, Mermaid theme selection

Markdown Presentation Tool

• Marketplace: https://marketplace.visualstudio.com/items?itemName=KunalPathak.markdown-presentation-tool
• Best for: Full Markdown decks with headings, text, Mermaid diagrams, code blocks, and images
• Highlights: <!-- slide --> delimiters, theme awareness, style controls, rich mixed-content slides

Both tools are published separately from this repository and complement the web/offline/Docker versions of Mermaid Slides.

Privacy & Security

Mermaid Slides is designed with privacy as a core principle:

• No Data Collection - Zero analytics, tracking, or telemetry
• Offline Operation - Full functionality without internet connection
• Local Processing - All diagram rendering happens on your device
• Self-Contained - No external CDN dependencies in any distribution
• Simple Local Servers - The offline package uses lightweight local Python or Node.js servers only
• No External Requests - All distributions make zero network calls during operation

Documentation

• Deployment Guide - Multi-channel deployment, release flow, and channel-specific notes
• Contributing Guide - Development workflow, testing, and release checklist
• Future Work - Planned follow-up improvements and rationale
• AI Agent Context - Workspace context and verified commands for coding agents

Technology

Frontend: React 19 + TypeScript | Build: Vite 7 | Styling: Tailwind CSS 3.4 Diagrams: Mermaid.js 11 | Testing: Vitest + React Testing Library | Deployment: GitHub Pages, offline package, Docker

Supported Content

Mermaid Diagrams: Flowcharts, Sequence, ER, Class, State, Gantt, Pie Charts, Git Graphs Images: PNG, JPEG, GIF, WebP with automatic scaling and responsive display

Contributing

We welcome contributions! See our Contributing Guidelines for development setup and guidelines.

License

MIT License - see LICENSE for details.

Acknowledgments

Mermaid Slides is built with and redistributes the following open source projects. I am grateful for their contributions to the community:

• https://github.com/mermaid-js/mermaid (MIT License) — Copyright (c) Knut Sveidqvist The core diagramming engine that makes this project possible
• https://github.com/***/react (MIT License) — Copyright (c) Meta Platforms, Inc. The foundation for our modern, interactive user interface
• https://github.com/vitejs/vite (MIT License) — Copyright (c) Evan You Lightning-fast development and build tooling
• https://github.com/tailwindlabs/tailwindcss (MIT License) — Copyright (c) Tailwind Labs, Inc. Utility-first CSS framework for rapid UI development
• https://github.com/microsoft/TypeScript (Apache-2.0 License) — Copyright (c) Microsoft Corporation Type safety and developer experience enhancements

See package.json for a complete list of all dependencies.

Special thanks to the Mermaid.js team for creating such a powerful and flexible diagramming library that enables developers to create beautiful diagrams with simple text syntax.

Try it now | Full Documentation | https://github.com/kanad13/mermaid-slides/issues