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

1. Maintain content hierarchy:

- H1 (#) for section titles - H2 (##) for main slide titles - H3 (###) for sub-topics

1. Preserve original organization and flow
2. 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:

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

1. 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: 🎯📊🤖💡🚀📚🔧⚡

1. Clean up comments:

- Remove markdown comments not meant for slides - Remove TODO items - Remove internal notes

1. Ensure clean format:

- Consistent spacing - Proper header hierarchy - Clear slide breaks

1. Add frontmatter (if requested):

``markdown slidenumbers: true ``

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

1. Verify existence before referencing - run ls or glob to confirm file exists
2. Maintain semantic relevance - image should match slide content
3. 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

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

1. Hierarchy:

- H1 for major sections (usually numbered) - H2 for main slide titles - H3 for subtopics within slides - Consistent numbering scheme

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