markdown-slides-cli 1.0.0

package/README.md

@@ -0,0 +1,440 @@
+# 📊 Markdown Slides
+
+> A powerful, interactive markdown slide presentation tool with live editing, minimap view, and fullscreen support. Create beautiful presentations from simple markdown files!
+
+![Node.js](https://img.shields.io/badge/node-%3E%3D14.0.0-brightgreen)
+![License](https://img.shields.io/badge/license-MIT-green)
+
+## ✨ Features
+
+- 📝 **Markdown-Based** - Write slides in simple markdown syntax
+- 🗺️ **Minimap View** - Navigate slides with thumbnail overview
+- ✏️ **Live Editor** - Built-in Monaco editor (VS Code's editor)
+- 🎨 **Beautiful Rendering** - Full markdown support with syntax highlighting
+- 📱 **Responsive Design** - Works on desktop, tablet, and mobile
+- 🎬 **Fullscreen Mode** - Present without distractions
+- ⌨️ **Keyboard Navigation** - Navigate with arrow keys and shortcuts
+- 💾 **Export Edited Slides** - Download your modified presentations
+- 🌙 **Dark Theme** - Easy on the eyes during presentations
+- 🚀 **Zero Config** - Works out of the box
+
+## 📦 Installation
+
+### Global Installation
+
+```bash
+npm install -g markdown-slides-cli
+```
+
+After global installation, you can use it anywhere:
+
+```bash
+markdown-slides -f presentation.md
+# or the shorter alias
+md-slides -f presentation.md
+```
+
+## 🚀 Quick Start
+
+### 1. Create Your Markdown File
+
+Create a file called `slides.md`:
+
+```markdown
+# Welcome to My Presentation
+This is the first slide
+
+---
+
+# Second Slide
+- Point 1
+- Point 2
+- Point 3
+
+---
+
+# Code Example
+```javascript
+function hello() {
+  console.log('Hello World!');
+}
+```
+```
+
+### 2. Run the Presentation
+
+```bash
+node markdown-slides.js -f slides.md
+```
+
+Or with global installation:
+
+```bash
+markdown-slides -f slides.md
+```
+
+Your browser will automatically open with your presentation!
+
+## 🎮 CLI Options
+
+| Option | Alias | Description | Default |
+|--------|-------|-------------|---------|
+| `--file` | `-f` | Markdown file path (required) | - |
+| `--port` | `-p` | Server port | `3457` |
+| `--title` | `-t` | Presentation title | `Markdown Slides` |
+| `--theme` | - | Slide theme (dark/light/blue) | `dark` |
+| `--help` | `-h` | Display help | - |
+
+### Examples
+
+```bash
+# Basic usage
+markdown-slides -f presentation.md
+
+# Custom port and title
+markdown-slides -f slides.md -p 8080 -t "My Presentation"
+
+# Different theme
+markdown-slides -f deck.md --theme blue
+```
+
+## ⌨️ Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `→` or `Space` | Next slide |
+| `←` | Previous slide |
+| `Home` | Go to first slide |
+| `End` | Go to last slide |
+| `F` or `F11` | Toggle fullscreen |
+| `E` | Open editor |
+| `M` | Toggle minimap |
+| `Esc` | Close editor / Exit fullscreen |
+
+## 📝 Markdown Syntax
+
+### Slide Separators
+
+Slides are separated by horizontal rules or top-level headers:
+
+**Method 1: Horizontal Rules**
+```markdown
+# Slide 1
+Content here
+
+---
+
+# Slide 2
+More content
+
+***
+
+# Slide 3
+Even more content
+```
+
+**Method 2: Top-Level Headers**
+```markdown
+# Slide 1
+Content
+
+# Slide 2
+Content
+
+# Slide 3
+Content
+```
+
+### Supported Markdown Features
+
+- **Headers**: `# H1` through `###### H6`
+- **Bold**: `**bold**` or `__bold__`
+- **Italic**: `*italic*` or `_italic_`
+- **Lists**: Ordered and unordered
+- **Code Blocks**: With syntax highlighting
+- **Inline Code**: `` `code` ``
+- **Links**: `[text](url)`
+- **Images**: `![alt](url)`
+- **Blockquotes**: `> quote`
+- **Tables**: Standard markdown tables
+- **Horizontal Rules**: `---` or `***`
+
+### Example Slide
+
+```markdown
+# My Awesome Slide 🚀
+
+## Key Points
+
+- **Important**: This is bold
+- *Emphasis*: This is italic
+- `code`: Inline code example
+
+## Code Example
+
+```javascript
+const greeting = "Hello World!";
+console.log(greeting);
+```
+
+> "This is a blockquote"
+
+| Feature | Status |
+|---------|--------|
+| Edit | ✅ |
+| View | ✅ |
+```
+
+## 🎨 Using the Editor
+
+### Opening the Editor
+
+1. Click the **"Edit"** button in the header
+2. Or press `E` on your keyboard
+
+### Editing Your Slides
+
+- The Monaco editor provides full VS Code-like experience
+- Syntax highlighting for markdown
+- Built-in minimap for long documents
+- Auto-completion and formatting
+
+### Applying Changes
+
+1. Make your edits in the Monaco editor
+2. Click **"Apply"** to update the presentation
+3. Or click **"Close"** to discard changes
+
+### Downloading Edited Slides
+
+Click the **"Download"** button in the editor to save your modified markdown file.
+
+## 🗺️ Minimap Navigation
+
+### Opening the Minimap
+
+1. Click the **"Minimap"** button in the header
+2. Or press `M` on your keyboard
+
+### Using the Minimap
+
+- View thumbnails of all slides
+- Current slide is highlighted
+- Click any thumbnail to jump to that slide
+- Minimap shows slide content preview
+
+## 🎬 Fullscreen Presentation
+
+### Entering Fullscreen
+
+1. Click the **"Fullscreen"** button
+2. Or press `F` or `F11`
+
+### Fullscreen Features
+
+- Header automatically hides
+- Navigation controls fade to semi-transparent
+- Full immersive presentation experience
+- Press `Esc` or `F11` to exit
+
+## 📖 Example Presentations
+
+### Simple Presentation
+
+```markdown
+# Introduction
+Welcome to my talk!
+
+---
+
+# Problem Statement
+What are we solving?
+- Issue 1
+- Issue 2
+- Issue 3
+
+---
+
+# Solution
+Here's how we fix it:
+1. Step one
+2. Step two
+3. Step three
+
+---
+
+# Conclusion
+Thank you! 🎉
+```
+
+### Technical Presentation
+
+```markdown
+# API Documentation
+
+---
+
+# REST Endpoints
+
+## GET /users
+Retrieve all users
+
+```json
+{
+  "users": [
+    {"id": 1, "name": "Alice"}
+  ]
+}
+```
+
+---
+
+# Authentication
+
+Use Bearer tokens:
+```bash
+curl -H "Authorization: Bearer TOKEN" /api/users
+```
+
+---
+
+#
+
+### Technologies Used
+
+- **Node.js** - Runtime environment
+- **Commander** - CLI argument parsing
+- **Marked** - Markdown parsing
+- **Monaco Editor** - Code editor (VS Code)
+- **Tailwind CSS** - Styling
+
+## 🤝 Use Cases
+
+- 📚 **Educational Content** - Teaching materials, tutorials
+- 💼 **Business Presentations** - Pitch decks, reports
+- 🎤 **Conference Talks** - Technical presentations
+- 📖 **Documentation** - Product demos, guides
+- 👨‍🏫 **Training Materials** - Workshops, courses
+- 📊 **Data Presentations** - Reports with code examples
+
+## 💡 Tips & Tricks
+
+### Creating Effective Slides
+
+1. **Keep It Simple** - One main idea per slide
+2. **Use Visual Hierarchy** - Headers, lists, emphasis
+3. **Add Code Examples** - With syntax highlighting
+4. **Include Emojis** - Make slides more engaging 🎉
+5. **Use Tables** - For structured data
+6. **Add Images** - Break up text-heavy slides
+
+### Presentation Tips
+
+1. **Test Before Presenting** - Preview all slides
+2. **Use Fullscreen** - Minimize distractions
+3. **Practice Navigation** - Learn keyboard shortcuts
+4. **Prepare Backup** - Download PDF version
+5. **Have Notes Ready** - Use separate notes file
+
+### Advanced Usage
+
+**Custom Styling**: Edit the embedded CSS in `markdown-slides.js`
+
+**Custom Themes**: Modify the color scheme in the `<style>` section
+
+**Hosting**: Deploy with any static file server or Node.js hosting
+
+## 🐛 Troubleshooting
+
+### Port Already in Use
+
+```bash
+# Use a different port
+markdown-slides -f slides.md -p 8080
+```
+
+### Browser Doesn't Open
+
+```bash
+# Manually open the URL shown in console
+# Usually: http://localhost:3457
+```
+
+### Editor Not Loading
+
+- Check internet connection (Monaco loads from CDN)
+- Try refreshing the page
+- Clear browser cache
+
+### Slides Not Rendering
+
+- Ensure markdown syntax is correct
+- Check for proper slide separators (`---`)
+- Verify file encoding is UTF-8
+
+## 📋 Requirements
+
+- Node.js >= 14.0.0
+- Modern web browser (Chrome, Firefox, Safari, Edge)
+- Internet connection (for CDN resources)
+
+## 📦 Dependencies
+
+- `commander` - CLI argument parsing
+
+All other features (Marked, Monaco Editor, Tailwind CSS) load from CDNs.
+
+## 🚀 Future Enhancements
+
+- [ ] Speaker notes support
+- [ ] Timer and progress indicator
+- [ ] Export to PDF
+- [ ] Custom themes/templates
+- [ ] Slide transitions and animations
+- [ ] Remote control via mobile
+- [ ] Collaborative editing
+- [ ] Drawing/annotation tools
+- [ ] Video embed support
+- [ ] Auto-save functionality
+
+
+
+## 📝 License
+
+MIT License (c) Mohan Chinnappan
+
+
+
+---
+
+## 📚 Quick Reference Card
+
+```
+┌─────────────────────────────────────────┐
+│     MARKDOWN SLIDES QUICK REFERENCE     │
+├─────────────────────────────────────────┤
+│ Start Server:                           │
+│   markdown-slides -f slides.md          │
+│                                         │
+│ Keyboard Shortcuts:                     │
+│   → / Space     Next slide              │
+│   ←             Previous slide          │
+│   Home          First slide             │
+│   End           Last slide              │
+│   F / F11       Fullscreen             │
+│   E             Open editor             │
+│   M             Toggle minimap          │
+│   Esc           Close / Exit            │
+│                                         │
+│ Slide Separator:                        │
+│   ---           (3 dashes)              │
+│   ***           (3 asterisks)           │
+│   # Header      (top level)             │
+└─────────────────────────────────────────┘
+```
+
+---
+
+**Made with ❤️ for presenters, educators, and developers**
+
+**Happy Presenting! 🎤✨**