Markdown Slides 🎯

A powerful full-screen presentation system that transforms markdown files into beautiful slide presentations. Built with React, TypeScript, and Tailwind CSS.

Quick Start • Features • Documentation • Examples

📚 Documentation: All documentation is organized in the docs/ directory. See the Documentation Index for the complete guide.

✨ Features

🎨 Beautiful Themes

Switch between 6 carefully crafted themes with light/dark modes. Each theme features unique typography and color palettes designed for maximum readability.

📂 Flexible Loading

Load presentations from local files or directly from Git URLs (GitHub/GitLab). No downloads needed.

⌨️ Keyboard Shortcuts

Lightning-fast navigation with intuitive keyboard shortcuts. Press ? to see all available shortcuts.

📱 Mobile Optimized

Fully responsive design with touch gestures. Swipe to navigate, pinch to zoom.

Complete Feature List

• 📝 Markdown-First - Write slides in familiar markdown syntax
• 🗺️ Mermaid Diagrams - Render flowcharts, sequence diagrams, ER diagrams, and more with fenced ```mermaid blocks
• 📊 Styled Tables - Responsive, striped data tables with accent headers rendered automatically
• ⌨️ Keyboard Shortcuts - Lightning-fast navigation with intuitive shortcuts
• 📱 Touch Support - Swipe gestures on mobile devices
• 🎨 Multiple Themes - 6 beautiful color schemes with light/dark modes
• 📂 Flexible Loading - Load from local files or Git URLs (GitHub/GitLab)
• ⏱️ Presentation Timer - Track your presentation time with pause/resume
• 🔍 Slide Search - Quick navigation with searchable slide list
• 📤 PDF Export - Export your presentation to PDF with one click
• ✨ Smooth Transitions - Polished animations and directional effects
• 🌐 Cross-Platform - Works on desktop, tablet, and mobile
• 🚀 CLI Ready - Run with npm or npx without installation
• 🎯 Fullscreen Mode - Distraction-free presenting experience
• 🤖 Agent Skill - agentskills.io-compatible skill so AI agents can create slide decks for this app

Why Markdown Slides?

Built for developers, by developers. Version control your presentations, collaborate with Git, and present with confidence.

🎬 Demo & Screenshots

Visual Feature Overview

See It In Action

The images above are SVG placeholders showing the features. To generate actual screenshots:

# Start the development server
npm run dev

# In another terminal, run the screenshot helper
chmod +x .github/screenshots/generate-screenshots.sh
.github/screenshots/generate-screenshots.sh

Or follow the Screenshot Instructions to manually capture images, or view the Visual Guide for detailed feature examples.

📋 Prerequisites

• Node.js 18.x or higher
• npm 8.x or higher

🚀 Quick Start

Option 1: Run Locally (Development)

For contributors or local testing:

# Clone the repository
git clone https://github.com/abudhahir/markdown-slide-prese.git
cd markdown-slide-prese

# Install dependencies
npm install

# Start development server with hot reload
npm run dev

The application will be available at http://localhost:5173

Option 2: Test the Production Build Locally

Build and run the production version:

# Build for production
npm run build

# Run the built version
npm run start

Open your browser to http://localhost:3000 and start presenting!

See the Testing and Local Deployment Guide for comprehensive testing instructions.

Option 3: Using npx (No Installation - After Publishing)

Once published to npm, users can run instantly without installing:

# Stable version
npx c-deck-lite

# Pre-release versions (for testing)
npx c-deck-lite@beta
npx c-deck-lite@alpha

Option 4: Global Installation (After Publishing)

After publishing to npm, install globally to use anywhere:

# Install stable version globally
npm install -g c-deck-lite

# Or install pre-release for testing
npm install -g c-deck-lite@beta
npm install -g c-deck-lite@alpha

# Run from anywhere
markdown-slides

CLI Options

# Run on default port 3000
markdown-slides

# Run on custom port
markdown-slides --port 8080
markdown-slides -p 5000

# Show help
markdown-slides --help

# Show version
markdown-slides --version

For complete CLI documentation, see the CLI Usage Guide.

🚢 Releases & Publishing

This project uses fully automated releases with GitHub Actions. Each release automatically includes:

• 📦 GitHub Release with changelog and build artifacts
• 🌐 GitHub Pages Deploy - Live demo updated instantly
• 📤 npm Publication - Package published to npm registry automatically
• 🐳 Docker Image - Container published to GHCR
• ✅ Version Management - Semantic versioning enforced

🚀 Quick Release (Automated npm Publishing)

Just push a tag - Everything else is automatic!

# Stable release
git tag v1.0.0
git push origin main
git push origin v1.0.0

# Pre-release (beta/alpha/rc)
git tag v1.2.0-beta.1
git push origin v1.2.0-beta.1

# That's it! The workflow automatically:
# ✅ Builds the application
# ✅ Creates GitHub release
# ✅ Publishes to npm (with correct tag)
# ✅ Deploys to GitHub Pages (stable only)
# ✅ Builds Docker image

🔖 Pre-Release Support

Pre-releases are fully supported for testing before stable releases:

| Version Type | Tag Format | npm Tag | Install Command | |-------------|------------|---------|-----------------| | Alpha | v1.2.0-alpha.1 | alpha | npm install c-deck-lite@alpha | | Beta | v1.2.0-beta.1 | beta | npm install c-deck-lite@beta | | Release Candidate | v1.2.0-rc.1 | rc | npm install c-deck-lite@rc | | Stable | v1.2.0 | latest | npm install c-deck-lite |

Key Points:

• Pre-releases won't affect stable users (they use different npm tags)
• GitHub Pages only deploys for stable releases
• Perfect for testing new features before general availability

See Pre-Release Guide for detailed instructions.

📦 npm Publishing Setup

Before your first release, add your npm token to GitHub:

1. Create npm token at npmjs.com/settings/tokens
2. Add to GitHub Secrets: Settings → Secrets → New secret
   • Name: NPM_TOKEN
   • Value: Your npm access token

That's all! Future releases will automatically publish to npm.

See Automated npm Publishing Guide for complete setup instructions.

Release Workflow Features

• ✅ Automated Changelog - Generated from commit messages
• ✅ GitHub Release - Created with assets and release notes
• ✅ npm Auto-Publish - Published to npm registry (with NPM_TOKEN)
• ✅ GitHub Pages - Live demo updated automatically
• ✅ Docker Build - Container published to GHCR
• ✅ Version Validation - Semantic versioning enforced
• ✅ Build Verification - Tested before publishing
• ✅ Release Notes - Updated with npm package info

Using Releases

Download build:

# From GitHub releases
wget https://github.com/abudhahir/markdown-slide-prese/releases/download/v1.0.0/markdown-slides-v1.0.0-dist.tar.gz
tar -xzf markdown-slides-v1.0.0-dist.tar.gz

Docker:

# Pull and run
docker pull ghcr.io/abudhahir/markdown-slide-prese:latest
docker run -p 8080:80 ghcr.io/abudhahir/markdown-slide-prese:latest

npm:

# Install specific version
npm install [email protected]

See RELEASE_WORKFLOW.md for complete documentation.

🛠️ Development Setup

Project Structure

markdown-slide-prese/
├── src/
│   ├── components/
│   │   ├── slides/          # Slide-related components
│   │   │   ├── SlidePresentation.tsx
│   │   │   ├── MarkdownRenderer.tsx   # Markdown + mermaid rendering
│   │   │   ├── FileSelector.tsx
│   │   │   ├── ThemeSelector.tsx
│   │   │   ├── SlidesListOverlay.tsx
│   │   │   └── ...
│   │   └── ui/              # Shadcn UI components
│   ├── lib/                 # Utility functions
│   │   ├── markdown-parser.ts
│   │   ├── themes.ts
│   │   └── utils.ts
│   ├── App.tsx              # Main application component
│   ├── index.css            # Global styles and themes
│   └── main.tsx             # Entry point
├── bin/
│   └── markdown-slides.js   # CLI entry point (Node.js HTTP server)
├── examples/                # Example presentations
│   └── quick-reference.md   # Default deck (loaded on startup)
├── markdown-slides-creator/ # Agent skill (agentskills.io format)
│   ├── SKILL.md
│   └── assets/
│       └── template.md
├── docs/                    # Documentation
├── e2e/                     # Playwright end-to-end tests
├── index.html               # Entry HTML
├── package.json
├── vite.config.ts
└── tsconfig.json

Available Scripts

# Start development server (port 5173)
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Run linting
npm run lint

# Kill process on port 5000 (if needed)
npm run kill

Development Tips

1. Hot Module Replacement (HMR): Changes are reflected instantly during development
2. TypeScript: Full type safety with strict mode enabled
3. ESLint: Automatic code quality checks
4. Tailwind CSS: Utility-first styling with v4 features
5. React 19: Using the latest React features

Adding New Themes

Edit src/index.css and add your theme configuration:

:root {
  --background: oklch(0.98 0 0);
  --foreground: oklch(0.20 0 0);
  --primary: oklch(0.45 0.15 260);
  /* ... other color variables */
}

Customizing Components

All UI components are in src/components/ui/ (shadcn components) and custom components in src/components/slides/.

📦 Publishing to npm

This package is ready to be published to npm. See the NPM Publishing Guide for detailed instructions.

Quick Publish Steps

1. Update package.json with your details:

   • Change name to your desired package name
   • Update author, repository, and homepage URLs
   • Ensure version is set correctly

2. Build and test:

   npm run build
   npm run start  # Test the CLI locally
   npm pack       # Create tarball for testing

3. Login and publish:

   npm login
   npm publish

4. Verify publication:

   npm view c-deck-lite
   npx c-deck-lite

After Publishing

Users can install and run your package:

# Run without installing
npx c-deck-lite

# Or install globally
npm install -g c-deck-lite
markdown-slides

See NPM_PUBLISHING_GUIDE.md for complete publishing documentation.

🌐 Deployment

This project can be deployed to various platforms:

GitHub Pages

Automated deployment using GitHub Actions. See GITHUB_PAGES_DEPLOYMENT.md for detailed instructions.

GitLab Pages

Deploy to GitLab Pages using GitLab CI. See GITLAB_PAGES_DEPLOYMENT.md for instructions.

Other Platforms

Deploy the dist/ folder to any static hosting:

• Netlify: Connect your repo or drag-and-drop dist/
• Vercel: Import your git repository
• AWS S3 + CloudFront: Upload dist/ to S3 bucket
• Azure Static Web Apps: GitHub integration available
• Firebase Hosting: firebase deploy

📖 Usage Guide

Running as CLI

# Quick start with npx (no install)
npx c-deck-lite

# Or install globally
npm install -g c-deck-lite
markdown-slides

# Custom port
markdown-slides --port 8080

# Show help
markdown-slides --help

See the CLI Usage Guide for complete CLI documentation.

Creating Slides

Slides are written in standard markdown, separated by --- (with blank lines on both sides):

# First Slide

Welcome to my presentation!

---

## Second Slide

- Point one
- Point two
- Point three

---

# Thank You!

All standard markdown is supported: headings, bold/italic, code blocks with syntax highlighting, blockquotes, ordered and unordered lists, task lists, links, images, and tables.

Mermaid Diagrams

Render diagrams inline using fenced ```mermaid blocks:

\```mermaid
flowchart TD
    A([Write Markdown]) --> B{Has slides?}
    B -- Yes --> C([Multiple Slides])
    B -- No  --> D([Single Slide])
    C --> E([Present!])
    D --> E
\```

Supported diagram types: flowchart, sequenceDiagram, classDiagram, erDiagram, gantt, pie.

Note: Avoid using emojis inside mermaid node labels — they cause the label text to clip in scaled SVGs.

Styled Tables

Markdown tables render as responsive, styled data tables with accent headers and striped rows:

| Feature       | Status |
|---------------|--------|
| Themes        | ✅ 6 built-in |
| Mermaid       | ✅ Rendered   |
| PDF Export    | ✅ One click  |

Keyboard Shortcuts

| Key | Action | Key | Action | |:---:|--------|:---:|--------| | → ↓ | Next slide | ← ↑ | Previous slide | | Space | Next slide | S | Show slides list | | T | Toggle theme | O | Open file selector | | D | Display filename | F | Fullscreen | | ? | Show shortcuts | Esc | Exit/Close |

Loading Presentations

Local Files

1. Press O to open the file selector
2. Navigate to your markdown file
3. Click to load the presentation

Git URLs

1. Press O to open the file selector
2. Switch to the "Git URL" tab
3. Paste a GitHub or GitLab URL
4. Click "Load from Git"

Supported formats:

• https://github.com/owner/repo/blob/main/slides.md
• https://gitlab.com/owner/repo/-/blob/main/slides.md

Themes

Choose from 6 carefully designed themes, each with light and dark modes:

| Theme | Description | Best For | |-------|-------------|----------| | Solarized | Classic balanced color scheme | General presentations | | Dracula | Popular dark theme with vibrant accents | Creative content | | Code Dark/Light | Technical coding-friendly themes | Technical talks | | Midnight | Deep indigo with cyan accents | Professional slides | | Forest | Natural green tones | Environmental topics | | Sunset | Warm browns and oranges | Warm, inviting talks |

Press T to open the theme selector and preview themes in real-time.

Exporting to PDF

1. Navigate to your presentation
2. Click the download icon in the top-right corner
3. Wait for PDF generation
4. PDF will download automatically to your browser's download folder

Note: Ensure all fonts and images are loaded before exporting for best results.

📚 Documentation & Resources

📁 All documentation has been organized into the docs/ directory. See the Documentation Index for the complete structure.

Getting Started

• README - Project overview and setup
• Testing and Local Deployment Guide - ⭐ Comprehensive testing guide for local deployment and npm publishing
• Quick Start - CLI Edition - Get started in 60 seconds with CLI
• CLI Usage Guide - Complete CLI reference and troubleshooting
• User Guide - Complete usage instructions

Release & Publishing

• Release Workflow Guide - Comprehensive release automation documentation
• Quick Start Release Guide - Create your first release in 5 minutes
• Version Bump Quick Reference - ⭐ Quick guide for automated version bumps and pre-releases
• Pre-Release Guide - Complete guide to alpha, beta, and RC releases
• Automated npm Publishing Guide - npm publishing automation
• NPM Publishing Guide - Publishing to npm registry
• Release Implementation - Implementation details and architecture
• Workflow Architecture - Visual workflow diagrams and flow
• Changelog - Version history and changes

Deployment Guides

• GitHub Pages Deployment - Deploy to GitHub Pages
• GitLab Pages Deployment - Deploy to GitLab Pages

Development

• Architecture - Technical architecture details
• Product Requirements Document - Project requirements and specifications
• VS Code Extension Guide - Create a VS Code extension
• Scripts Documentation - Helper scripts for releases

Example Presentations

Example markdown files are included in the examples/ directory:

| File | Description | Best For | |------|-------------|----------| | 📚 tutorial.md | Feature showcase and complete tutorial | Learning the system | | 💻 technical-presentation.md | Technical presentation template | Developer talks | | 🎯 product-demo.md | Product demo template | Product launches |

Try them out: Press O and navigate to the examples/ folder to load any example.

🔧 Technical Details

Built With

• React 19
• TypeScript 5.7
• Tailwind CSS 4
• Framer Motion
• Marked (Markdown parsing)
• shadcn/ui components
• Vite (Build tool)

Browser Support

Modern browsers with ES2020+ support:

• Chrome/Edge 88+
• Firefox 78+
• Safari 14+

Key Dependencies

• marked - Markdown parsing
• framer-motion - Smooth animations
• html2canvas & jspdf - PDF export
• octokit - GitHub/GitLab API integration
• sonner - Toast notifications

🤝 Contributing

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Clone your fork

   git clone https://github.com/yourusername/markdown-slides.git

3. Create a feature branch

   git checkout -b feature/amazing-feature

4. Make your changes
   • Write clean, documented code
   • Follow existing code style
   • Add tests if applicable
5. Commit your changes

   git commit -m 'Add amazing feature'

6. Push to your fork

   git push origin feature/amazing-feature

7. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Use functional components and hooks
• Maintain existing code style
• Write meaningful commit messages
• Update documentation as needed

🐛 Troubleshooting

Common Issues

Slides not loading from Git URL

• Ensure the URL points to a raw markdown file
• Check that the repository is public
• Verify the file extension is .md or .markdown

PDF export fails

• Ensure all fonts are loaded
• Try reducing the number of slides
• Check browser console for specific errors

Theme not persisting

• Check that browser localStorage is enabled
• Try clearing browser cache
• Re-select the theme

Keyboard shortcuts not working

• Click on the presentation area to focus
• Check that no dialog is open
• Ensure you're not in an input field

🗺️ Roadmap

Future enhancements planned:

• [ ] CLI tool for standalone presentations
• [ ] Speaker notes support
• [ ] Presentation recording
• [ ] Real-time collaboration
• [ ] Custom theme creator UI
• [ ] Plugin/extension system
• [ ] Export to PPTX format
• [ ] Slide transitions customization
• [ ] Drawing/annotation tools
• [ ] Multi-language support

📄 License

MIT License - see the LICENSE file for details.

The Spark Template files and resources from GitHub are licensed under the terms of the MIT license, Copyright GitHub, Inc.

🙏 Acknowledgments

• Inspired by easy-slides
• Built with React
• Styled with Tailwind CSS
• UI components from shadcn/ui
• Markdown parsing with marked
• Animations with Framer Motion

📧 Contact Information

Project Maintainer

Author: abudhahir
Email: [email protected]
GitHub: @abudhahir
Project Repository: github.com/abudhahir/markdown-slides Live Demo: markdown-slides-abudhahir.github.app

Get in Touch

We'd love to hear from you! Here are the best ways to reach out:

For Project-Related Questions

• 📖 Documentation: Check the comprehensive guides in this repository
• 💬 GitHub Discussions: Start a discussion for questions, ideas, or showcasing your presentations
• 💡 Feature Requests: Open an issue with the enhancement label

For Bug Reports & Issues

• 🐛 Bug Reports: Open an issue with detailed reproduction steps
• 🔍 Search Existing Issues: Check if your issue has already been reported or resolved

For Collaboration & Contributions

• 🤝 Pull Requests: Submit PRs for bug fixes, features, or documentation improvements
• 📝 Contributing Guide: See Contributing section above
• 👥 Code Review: We review all PRs promptly and provide constructive feedback

For Direct Communication

• 📧 Email: For private inquiries, security issues, or partnership opportunities: [email protected]
• 🔒 Security Issues: Please email security-related issues privately before public disclosure

Stay Updated

• ⭐ Star this repo to get notifications about updates and releases
• 👁️ Watch this repo to follow all discussions and issues
• 📰 Release Notes: Check CHANGELOG.md for version updates

Community Guidelines

When reaching out, please:

• ✅ Be respectful and constructive
• ✅ Provide clear, detailed information
• ✅ Search existing issues/discussions first
• ✅ Follow our Code of Conduct
• ✅ Use appropriate issue templates

Response Time

We aim to respond to:

• 🐛 Critical bugs: Within 24 hours
• 💡 Feature requests: Within 1 week
• 💬 Discussions/Questions: Within 3-5 days
• 🤝 Pull requests: Within 1 week

Please note that this is an open-source project maintained by volunteers. Response times may vary.

📧 Support & Community

• 📖 Documentation: Check the guides in this repository
• 🐛 Bug Reports: Open an issue on GitHub
• 💡 Feature Requests: Open an issue with the enhancement label
• 💬 Questions: Start a discussion on GitHub Discussions
• 🌟 Show Support: Star this repository if you find it useful!

Made with ❤️ for presenters everywhere

Happy presenting! 🎉