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:

![]()

![](background.png)

![inline]()

![inline](diagram.svg)

![right fit]()

![right fit](chart.png)

![right 80%]()

![right 80%](image.png)

![inline fill]()

![inline fill](wide.png)

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

^ 

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 (

:

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