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