markdown-slides

name	markdown-slides
description	Create presentation slides in Markdown format (Deckset/Marp compatible). Use when user requests to create slides, presentations, or convert documents to slide format. Handles image positioning, speaker notes, and proper formatting.
allowed-tools	["Read","Write","Glob","Bash"]
license	MIT

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:

slidenumbers: true
# 1. Section Title 🎯

![](section-background.png)

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

# Section Title
![](background-image.png)

---

## Content Slide
Key points here:
- Point 1
- Point 2

![right fit](diagram.png)

---

## Inline Diagram
Text before diagram.

![inline](process-flow.svg)

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

<!-- This is a speaker note for Marp -->

Examples:

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

   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:

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:

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:

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