markdown-slides

# Markdown Slides Skill Convert content to presentation slides in Markdown format compatible with Deckset and Marp presentation tools. ## When to Use This Skill Activate this skill when the user: - Asks to create slides or a presentation - Requests to convert a document to slide format - Mentions Deckset or Marp - Wants to generate speaker notes - Needs to format images for presentations ## Input Requirements - **Source content**: Markdown file, outline, or structured content - **Images**: Files in `_files_/` directory or paths to be resolved - **Target platform**: Deckset (default) or Marp - **Options**: - Speaker notes (enabled by default) - Slide numbering (optional frontmatter) - Emoji enhancement (enabled by default) ## Output Specifications - **File location**: Same folder as source - **File naming**: Original name with `- slides` suffix - Example: `document.md` → `document - slides.md` - **Format**: Deckset-compatible markdown - **Structure**: Proper slide dividers, image tags, speaker notes - **Enhancement**: Emojis added for visual appeal ## Main Process ### Step 1: Slide Structure Setup **Objective**: Create logical slide divisions with proper hierarchy **Actions**: 1. Read and analyze source content structure 2. Insert slide dividers (`---`) at logical breaks: - Between major sections - Between distinct topics - After section intro slides - Before/after major diagrams 3. Maintain content hierarchy: - H1 (`#`) for section titles - H2 (`##`) for main slide titles - H3 (`###`) for sub-topics 4. Preserve original organization and flow 5. Add optional frontmatter: `slidenumbers: true` **Example**: ```markdown slidenumbers: true # 1. Section Title 🎯  ^ Introduction to this section. --- ## Main Topic 📊 Content here... --- ### Detailed Subtopic More details... ``` ### Step 2: Image Format Conversion **Objective**: Convert images to Deckset format with proper positioning **Critical Requirements**: ⚠️ **MUST resolve relative paths per-image basis** ⚠️ **MUST URL-encode spaces and escape special characters** ⚠️ **MUST verify image files exist** **Image Position Formats**: | Format | Usage | Example | |--------|-------|---------| | `![]()` | Section intro backgrounds | `` | | `![inline]()` | Diagrams within text flow | `` | | `![right fit]()` | **PRIMARY**: Content slides | `` | | `![right 80%]()` | Specific sizing needed | `` | | `![inline fill]()` | Full-width inline | `` | **Actions**: 1. Identify all image references in source 2. For each image: ``` a. Determine appropriate position format b. Resolve relative path from slide file location c. URL-encode spaces: " " → "%20" d. Escape parentheses: "(" → "%28", ")" → "%29" e. Verify file exists at resolved path f. Use original images when available g. Copy missing images to _files_/ directory ``` 3. Apply positioning based on context: - **Section intros**: Use `![]()` for full background - **Diagrams in text**: Use `![inline]()` - **Default for content slides**: Use `![right fit]()` ⭐ - **Custom sizing**: Use `![right XX%]()` when needed - **Full-width inline**: Use `![inline fill]()` for wide images **Examples**: ```markdown # Section Title  --- ## Content Slide Key points here: - Point 1 - Point 2  --- ## Inline Diagram Text before diagram.  Text after diagram. ``` ### Step 3: Speaker Notes Conversion **Objective**: Convert appropriate content to speaker notes **Format**: Lines starting with `^ ` (caret + space) **Placement**: At the end of each slide **Convert to speaker notes**: ✅ Multi-sentence paragraphs ✅ Explanatory text ✅ Additional context ✅ Talking points **DO NOT convert**: ❌ Single-sentence paragraphs ❌ Lists (bullet or numbered) ❌ Block quotes ❌ Sentences ending with colon (`:`) ❌ Headers (H1, H2, H3) ❌ Table content **For Marp platform**: Use HTML comments instead ```markdown <!-- This is a speaker note for Marp --> ``` **Examples**: ```markdown ## Slide Title Main content visible to audience. ^ This paragraph becomes a speaker note because it's multi-sentence explanatory text. It provides context that the speaker needs but the audience doesn't need to read on the slide. --- ## Another Slide - Bullet points stay visible - Not converted to notes ^ Additional speaking points go here. ``` ### Step 4: Content Enhancement **Objective**: Polish the presentation for maximum impact **Actions**: 1. **Add emojis** to section and slide titles: - Use relevant emojis that enhance meaning - Don't overuse - keep it professional - Examples: 🎯📊🤖💡🚀📚🔧⚡ 2. **Clean up comments**: - Remove markdown comments not meant for slides - Remove TODO items - Remove internal notes 3. **Ensure clean format**: - Consistent spacing - Proper header hierarchy - Clear slide breaks 4. **Add frontmatter** (if requested): ```markdown slidenumbers: true ``` 5. **Final review**: - Each slide has clear focus - Images positioned correctly - Speaker notes placed at end - No orphaned content ## Critical Guidelines ### Image Handling ⚠️ **CRITICAL RULES**: 1. **NEVER invent images** - Only reference images that exist in the source document or `_files_/` folder. Do NOT create placeholder references like `background-xxx.png` for images that don't exist. 2. **Use original images** from source when available 3. **Copy missing images** to `_files_/` directory rather than substituting 4. **Resolve paths per-image** - don't assume same directory 5. **URL-encode spaces**: `my file.png` → `my%20file.png` 6. **Escape special characters**: - Parentheses: `(` → `%28`, `)` → `%29` - Other special chars as needed 7. **Verify existence** before referencing - run `ls` or glob to confirm file exists 8. **Maintain semantic relevance** - image should match slide content 9. **Section intros without images are OK** - If no background image exists for a section intro slide, just use the title and speaker notes without an image reference ### Image Position Standards **Decision tree for image positioning**: ``` Is it a section intro slide with just title? → Does a background image exist? → YES: Use ![]() for full background → NO: Skip image, use title + speaker notes only Is it a diagram embedded in flowing text? → YES: Use ![inline]() or ![inline fill]() Is it the main visual for the slide with bullet points? → YES: Use ![right fit]() ⭐ PRIMARY FORMAT Does it need specific sizing? → YES: Use ![right 80%]() or other percentage ``` ### Speaker Notes Rules **When to convert to speaker notes**: - Multi-sentence explanatory paragraphs - Contextual information not needed on slide - Talking points for the speaker - Additional details for verbal explanation **When NOT to convert**: - Single-sentence paragraphs (might be slide content) - Bullet or numbered lists (usually slide content) - Block quotes (usually featured content) - Sentences ending with `:` (usually introducing lists) - Any header level - Table content **Format**: ```markdown Slide content here. ^ Speaker note paragraph one. Can be multiple sentences providing context. ^ Speaker note paragraph two. Each note paragraph gets its own ^ prefix. ``` ### Content Standards 1. **File Naming**: - Always use `- slides` suffix - Preserve original filename otherwise - Example: `AI for PKM.md` → `AI for PKM - slides.md` 2. **Emoji Usage**: - Add to H1 and H2 headers - Choose relevant, professional emojis - Don't overuse - quality over quantity - Examples: - 🎯 Goals/Objectives - 📊 Data/Charts - 🤖 AI/Technology - 💡 Ideas/Insights - 🚀 Future/Launch - 📚 Learning/Knowledge 3. **Hierarchy**: - H1 for major sections (usually numbered) - H2 for main slide titles - H3 for subtopics within slides - Consistent numbering scheme 4. **Slide Breaks**: - Use `---` (three dashes) on its own line - Blank line before and after recommended - Logical breaks between topics ## Platform-Specific Notes ### Deckset (Default) **Format**: - Speaker notes: `^ ` prefix on each line - Image positioning: All formats fully supported - Frontmatter: Simple key-value pairs **Features**: - Automatic slide numbering with `slidenumbers: true` - Full control over image positioning - Rich presenter notes support **Example Frontmatter**: ```markdown slidenumbers: true autoscale: true theme: Plain Jane, 3 ``` ### Marp (Optional) **Format**: - Speaker notes: HTML comments `<!-- speaker note -->` - Image positioning: May use different syntax - Frontmatter: YAML with `marp: true` **Conversion for Marp**: ```markdown --- marp: true paginate: true --- <!-- This is a speaker note in Marp --> ``` **Differences**: - HTML comments instead of `^` prefix - Different frontmatter structure - May need `![bg]()` for backgrounds instead of `![]()` ## Quality Checklist Before marking task complete, verify: - [ ] **No invented images** - every image reference points to a real file - [ ] All images have valid, URL-encoded paths - [ ] Image files exist at specified locations (run `ls` to confirm) - [ ] Spaces in paths converted to `%20` - [ ] Special characters properly escaped - [ ] Speaker notes use `^ ` prefix (or HTML for Marp) - [ ] Speaker notes placed at END of each slide - [ ] Slide dividers (`---`) at logical breaks - [ ] Consistent header hierarchy (H1 → H2 → H3) - [ ] Emojis added appropriately to titles - [ ] File saved with '- slides' suffix - [ ] Content hierarchy maintained from source - [ ] No orphaned content or broken sections - [ ] Internal comments removed - [ ] Frontmatter added if requested ## Error Handling ### Missing Images **Problem**: Source references image that doesn't exist **Solution**: 1. Check source `_files_/` directory 2. Check parent directory `_files_/` 3. Search for image by name in project 4. If found: Copy to presentation `_files_/` directory 5. If not found: Note in speaker notes and skip image ### Broken Relative Paths **Problem**: Path doesn't resolve correctly **Solution**: 1. Determine slide file location 2. Calculate relative path from slide to image 3. Test path resolution 4. URL-encode the working path ### Invalid Characters in Paths **Problem**: Special characters break image links **Solution**: - Spaces: Convert to `%20` - Parentheses: `(` → `%28`, `)` → `%29` - Brackets: `[` → `%5B`, `]` → `%5D` - Other special chars: Use URL encoding ## Tips for Best Results 1. **Start with outline**: Create clear section and slide structure first 2. **One idea per slide**: Each slide should have single clear message 3. **Visual hierarchy**: Use H1 for sections, H2 for slides, H3 for sub-points 4. **Image positioning**: Default to `![right fit]()` for content slides 5. **Speaker notes**: Add context that helps speaker but clutters slide 6. **Emoji consistency**: Use similar emojis for similar concepts 7. **Test in Deckset**: Preview the slides to verify formatting 8. **Iterate**: First pass for structure, second for polish