kunalpathak13/mermaid-slides repository overview

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

⁠Quick Start

⁠Online (Recommended)

Visit Mermaid Slides⁠ and start creating presentations immediately.

⁠Docker Container

Run Mermaid Slides in a Docker container for easy deployment:

# 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:

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

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

⁠Thanks Mermaid.js Team!

⁠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: 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: 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:

• Mermaid.js⁠ (MIT License) — Copyright (c) Knut Sveidqvist The core diagramming engine that makes this project possible
• React⁠ (MIT License) — Copyright (c) Meta Platforms, Inc. The foundation for our modern, interactive user interface
• Vite⁠ (MIT License) — Copyright (c) Evan You Lightning-fast development and build tooling
• Tailwind CSS⁠ (MIT License) — Copyright (c) Tailwind Labs, Inc. Utility-first CSS framework for rapid UI development
• 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⁠ | Report Issues⁠