MD Show

A markdown presentation tool that supports SQL queries, Mermaid diagrams, dynamic slide creation, and interactive audience polling.

Features

🎬 Dual View Mode

• Default Markdown View: Start with a clean, readable markdown format
• Slide View: Switch to presentation mode with a "Play Slides" button
• Seamless toggle between views

🔄 Dynamic Slide Creation

• Click on SQL queries to execute them
• Automatically creates new slides with query results
• Inherits headers from source slides
• Prevents multiple loads from the same query
• Shows loading states and execution timers

📊 Query Results

• Tables: Automatic table generation for query results
• Charts: Plotly integration for x/y data visualization
• Real-time: Live query execution with progress indicators

🎨 Mermaid Diagrams

• Support for flowcharts, sequence diagrams, and more
• Click to zoom functionality
• Export to SVG
• Error handling with source code display

🗳️ Interactive Audience Polling

• Real-time voting: Audience can vote on questions during presentations
• Live results: Dynamic progress bars showing vote distribution
• TimescaleDB integration: Time-series storage for poll events
• Session tracking: Unique audience member identification
• Responsive design: Works on mobile and desktop devices

🎯 Smart Features

• Language detection for code blocks
• Syntax highlighting for multiple languages
• Responsive design for mobile devices
• Toast notifications for user feedback

Installation

gem install md-show

Usage

Basic Usage

md-show your-presentation.md

With Database Connection

md-show your-presentation.md "postgresql://user:password@localhost/dbname"

Or set the PG_URI environment variable:

export PG_URI="postgresql://user:password@localhost/dbname"
md-show your-presentation.md

Markdown Features

SQL Queries

Click on SQL code blocks to execute them:

SELECT 1 as id, 'Test' as name, 42 as value;

Charts

Queries with x and y columns automatically create charts:

SELECT 1 as x, 10 as y
UNION ALL
SELECT 2 as x, 20 as y;

Mermaid Diagrams

graph TD
    A[Start] --> B{Is it working?}
    B -->|Yes| C[Great!]
    B -->|No| D[Debug]
    C --> E[End]
    D --> E

Loading

Interactive Polls

Create audience polls using simple markdown syntax:

What's your favorite database?
* PostgreSQL
* MySQL
* MongoDB
* Redis

The system automatically converts these into interactive voting buttons with real-time results.

View Modes

Default Markdown View

• Clean, readable format
• Perfect for editing and reviewing content
• All interactive features work

Slide View

• Full-screen presentation mode
• Keyboard navigation
• Dynamic slide creation
• Professional presentation experience

Dynamic Slide Creation

When you click on a SQL query:

1. Loading State: Query shows processing indicator
2. Execution: Query runs against your database
3. Slide Creation: New slide is added after the source slide
4. Navigation: Automatically moves to the new slide
5. Results: Displays results with inherited headers

Features

• ✅ Prevents multiple loads from same query
• ✅ Inherits headers from source slides
• ✅ Supports both tables and charts
• ✅ Shows execution time
• ✅ Toast notifications
• ✅ Error handling

Interactive Polling

Creating Polls

Use simple markdown syntax to create interactive polls:

Question to the audience?
* Answer A
* Answer B
* Answer C

Poll Features

• Real-time voting: Audience clicks buttons to vote
• Live results: Progress bars update automatically
• Session tracking: Each audience member gets a unique session ID
• TimescaleDB storage: All votes stored in time-series hypertable
• Mobile responsive: Works on all devices

Poll Results

Results are displayed with:

• Progress bars: Visual representation of vote distribution
• Percentages: Exact vote percentages
• Vote counts: Total votes per option
• Real-time updates: Results refresh every 2 seconds

Technical Implementation

The polling system uses TimescaleDB for:

• Hypertable storage: Efficient time-series data storage
• Real-time aggregation: Fast vote counting and analysis
• Session management: Unique audience member tracking
• Performance optimization: Automatic compression and indexing

Configuration

Database Connection

The application supports PostgreSQL connections via:

1. Command line argument: md-show file.md "postgresql://..."
2. Environment variable: PG_URI="postgresql://..."
3. Default: Uses ENV['PG_URI']

TimescaleDB Setup

The polling feature requires TimescaleDB extension:

CREATE EXTENSION IF NOT EXISTS timescaledb;

The system automatically creates the required hypertables on first use.

Supported Languages

The application automatically detects and highlights:

• SQL
• JavaScript/TypeScript
• Python
• Ruby
• Go
• Rust
• Java/C#
• CSS/SCSS
• JSON/YAML
• Shell scripts
• And many more...

Development

Running from Source

git clone https://github.com/your-repo/md-show.git
cd md-show
bundle install
ruby bin/md-show your-file.md

Testing

bundle exec rspec

Testing Polling Feature

Create a markdown file with polls:

# Demo Presentation

What's your favorite color?
* Red
* Blue
* Green
* Yellow

Run the presentation:

md-show demo.md "postgresql://user:password@localhost/dbname"

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE.txt file for details.