markdown-slides

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Markdown Slides Skill

Markdown 幻灯片制作技能

Convert content to presentation slides in Markdown format compatible with Deckset and Marp presentation tools.

将内容转换为兼容Deckset和Marp演示工具的Markdown格式幻灯片。

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

当用户有以下需求时激活此技能：

请求创建幻灯片或演示文稿
需要将文档转换为幻灯片格式
提到Deckset或Marp
想要生成演讲者备注
需要为演示文稿格式化图片

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)

源内容：Markdown文件、大纲或结构化内容
图片：位于
```
_files_/
```
目录下的文件或待解析的路径
目标平台：Deckset（默认）或Marp
选项：
- 演讲者备注（默认启用）
- 幻灯片编号（可选前置配置）
- 表情符号增强（默认启用）

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

文件位置：与源文件同一文件夹
文件命名：原文件名后添加
```
- slides
```
后缀
- 示例：
```
document.md
```
  →
```
document - slides.md
```
格式：兼容Deckset的Markdown格式
结构：正确的幻灯片分隔符、图片标签、演讲者备注
增强：添加表情符号提升视觉效果

Main Process

主要流程

Step 1: Slide Structure Setup

步骤1：幻灯片结构设置

Objective: Create logical slide divisions with proper hierarchy

Actions:

Read and analyze source content structure
Insert slide dividers (
```
---
```
) at logical breaks:
- Between major sections
- Between distinct topics
- After section intro slides
- Before/after major diagrams
Maintain content hierarchy:
- H1 (
```
#
```
  ) for section titles
- H2 (
```
##
```
  ) for main slide titles
- H3 (
```
###
```
  ) for sub-topics
Preserve original organization and flow
Add optional frontmatter:
```
slidenumbers: true
```

Example:

markdown

slidenumbers: true

目标：创建具有合理层级的逻辑幻灯片划分

操作：

读取并分析源内容结构
在逻辑断点处插入幻灯片分隔符(
```
---
```
)：
- 主要章节之间
- 不同主题之间
- 章节介绍幻灯片之后
- 重要图表前后
保持内容层级：
- H1(
```
#
```
  )用于章节标题
- H2(
```
##
```
  )用于主幻灯片标题
- H3(
```
###
```
  )用于子主题
保留原有的内容组织和流程
添加可选前置配置：
```
slidenumbers: true
```

示例：

markdown

slidenumbers: true

1. Section Title 🎯

1. 章节标题 🎯

^ Introduction to this section.

^ 本章节介绍。

Main Topic 📊

主主题 📊

Content here...

此处为内容...

Detailed Subtopic

详细子主题

More details...

undefined

更多细节...

undefined

Step 2: Image Format Conversion

步骤2：图片格式转换

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	`![](background.png)`
`![inline]()`	Diagrams within text flow	`![inline](diagram.svg)`
`![right fit]()`	PRIMARY: Content slides	`![right fit](chart.png)`
`![right 80%]()`	Specific sizing needed	`![right 80%](image.png)`
`![inline fill]()`	Full-width inline	`![inline fill](wide.png)`

Actions:

Identify all image references in source

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

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

undefined

目标：将图片转换为Deckset格式并设置合理位置

关键要求： ⚠️ 必须逐张解析相对路径 ⚠️ 必须对空格进行URL编码并转义特殊字符 ⚠️ 必须验证图片文件是否存在

图片位置格式：

格式	用途	示例
`![]()`	章节介绍背景图	`![](background.png)`
`![inline]()`	文本流中的图表	`![inline](diagram.svg)`
`![right fit]()`	主要格式：内容幻灯片	`![right fit](chart.png)`
`![right 80%]()`	需要特定尺寸时使用	`![right 80%](image.png)`
`![inline fill]()`	全宽内联图片	`![inline fill](wide.png)`

操作：

识别源内容中的所有图片引用

对每张图片执行以下操作：

a. 确定合适的位置格式
b. 解析相对于幻灯片文件位置的相对路径
c. 对空格进行URL编码：" " → "%20"
d. 转义括号："(" → "%28", ")" → "%29"
e. 验证解析后的路径下文件是否存在
f. 优先使用源文件中的原始图片
g. 将缺失的图片复制到`_files_/`目录

根据上下文设置图片位置：
- 章节介绍：使用
```
![]()
```
  设置全屏背景
- 文本中的图表：使用
```
![inline]()
```
- 内容幻灯片默认格式：使用
```
![right fit]()
```
  ⭐
- 自定义尺寸：需要时使用
```
![right XX%]()
```
- 全宽内联：宽图使用
```
![inline fill]()
```

示例：

markdown

undefined

Section Title

章节标题

Content Slide

内容幻灯片

Key points here:

Point 1
Point 2

要点如下：

要点1
要点2

Inline Diagram

内联图表

Text before diagram.

Text after diagram.

undefined

图表前的文本。

图表后的文本。

undefined

Step 3: Speaker Notes Conversion

步骤3：演讲者备注转换

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

undefined

目标：将合适的内容转换为演讲者备注

格式：以

（脱字符+空格）开头的行

位置：位于每张幻灯片的末尾

需转换为备注的内容： ✅ 多段落句子 ✅ 解释性文本 ✅ 额外上下文信息 ✅ 演讲要点

无需转换的内容： ❌ 单句段落 ❌ 列表（项目符号或编号） ❌ 块引用 ❌ 以冒号(

)结尾的句子 ❌ 标题（H1、H2、H3） ❌ 表格内容

针对Marp平台：使用HTML注释替代

markdown

<!-- 这是Marp中的演讲者备注 -->

示例：

markdown

undefined

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.

undefined

项目符号保持可见
不会被转换为备注

^ 额外的演讲要点放在这里。

undefined

Step 4: Content Enhancement

步骤4：内容增强

Objective: Polish the presentation for maximum impact

Actions:

Add emojis to section and slide titles:
- Use relevant emojis that enhance meaning
- Don't overuse - keep it professional
- Examples: 🎯📊🤖💡🚀📚🔧⚡
Clean up comments:
- Remove markdown comments not meant for slides
- Remove TODO items
- Remove internal notes
Ensure clean format:
- Consistent spacing
- Proper header hierarchy
- Clear slide breaks
Add frontmatter (if requested):
markdown
```
slidenumbers: true
```
Final review:
- Each slide has clear focus
- Images positioned correctly
- Speaker notes placed at end
- No orphaned content

目标：优化演示文稿以实现最佳效果

操作：

为章节和幻灯片标题添加表情符号：
- 使用能增强含义的相关表情符号
- 不要过度使用——保持专业性
- 示例：🎯📊🤖💡🚀📚🔧⚡
清理注释：
- 删除不适用于幻灯片的Markdown注释
- 删除TODO项
- 删除内部备注
确保格式整洁：
- 一致的间距
- 规范的标题层级
- 清晰的幻灯片分隔
添加前置配置（如果有要求）：
markdown
```
slidenumbers: true
```
最终审核：
- 每张幻灯片都有明确的核心内容
- 图片位置正确
- 演讲者备注放置在末尾
- 无孤立内容或损坏的章节

Critical Guidelines

关键指南

Image Handling

图片处理

⚠️ CRITICAL RULES:

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.
Use original images from source when available
Copy missing images to
```
_files_/
```
directory rather than substituting
Resolve paths per-image - don't assume same directory
URL-encode spaces:
```
my file.png
```
→
```
my%20file.png
```
Escape special characters:
- Parentheses:
```
(
```
  →
```
%28
```
  ,
```
)
```
  →
```
%29
```
- Other special chars as needed
Verify existence before referencing - run
```
ls
```
or glob to confirm file exists
Maintain semantic relevance - image should match slide content
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

⚠️ 关键规则：

切勿虚构图片——仅引用源文档或
```
_files_/
```
文件夹中存在的图片。不要为不存在的图片创建占位符引用，如
```
background-xxx.png
```
。
优先使用源文件中的原始图片
将缺失的图片复制到
```
_files_/
```
目录，而非替换
逐张解析路径——不要假设所有图片都在同一目录
URL编码空格：
```
my file.png
```
→
```
my%20file.png
```
转义特殊字符：
- 括号：
```
(
```
  →
```
%28
```
  ,
```
)
```
  →
```
%29
```
- 其他特殊字符按需转义
引用前验证文件存在——运行
```
ls
```
或全局搜索确认文件存在
保持语义相关性——图片应与幻灯片内容匹配
无图片的章节介绍也可接受——如果章节介绍幻灯片没有背景图片，仅使用标题和演讲者备注即可

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

图片位置决策树：

是否为仅含标题的章节介绍幻灯片？
  → 是否存在背景图片？
    → 是：使用![]()设置全屏背景
    → 否：跳过图片，仅使用标题+演讲者备注

是否为嵌入在文本流中的图表？
  → 是：使用![inline]()或![inline fill]()

是否为带有项目符号的内容幻灯片的主视觉图？
  → 是：使用![right fit]() ⭐ 主要格式

是否需要特定尺寸？
  → 是：使用![right 80%]()或其他百分比

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.

需转换为备注的场景：

多句解释性段落
幻灯片上不需要的上下文信息
演讲者的演讲要点
用于口头解释的额外细节

无需转换的场景：

单句段落（可能是幻灯片内容）
项目符号或编号列表（通常是幻灯片内容）
块引用（通常是重点内容）
以
```
:
```
结尾的句子（通常用于引出列表）
任何级别的标题
表格内容

格式：

markdown

此处为幻灯片内容。

^ 演讲者备注第一段。可以是提供上下文的多句内容。

^ 演讲者备注第二段。每个备注段落都有自己的^前缀。

Content Standards

内容标准

File Naming:
- Always use
```
- slides
```
  suffix
- Preserve original filename otherwise
- Example:
```
AI for PKM.md
```
  →
```
AI for PKM - slides.md
```
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
Hierarchy:
- H1 for major sections (usually numbered)
- H2 for main slide titles
- H3 for subtopics within slides
- Consistent numbering scheme
Slide Breaks:
- Use
```
---
```
  (three dashes) on its own line
- Blank line before and after recommended
- Logical breaks between topics

文件命名：
- 始终添加
```
- slides
```
  后缀
- 保留原文件名的其他部分
- 示例：
```
AI for PKM.md
```
  →
```
AI for PKM - slides.md
```
表情符号使用：
- 添加到H1和H2标题
- 选择相关、专业的表情符号
- 不要过度使用——重质不重量
- 示例：
  - 🎯 目标/目的
  - 📊 数据/图表
  - 🤖 AI/技术
  - 💡 想法/见解
  - 🚀 未来/发布
  - 📚 学习/知识
层级结构：
- H1用于主要章节（通常带编号）
- H2用于主幻灯片标题
- H3用于幻灯片内的子主题
- 一致的编号方案
幻灯片分隔：
- 使用
```
---
```
  （三个短横线）单独占一行
- 建议前后各留一个空行
- 在主题之间进行逻辑分隔

Platform-Specific Notes

平台特定说明

Deckset (Default)

Deckset（默认）

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

格式：

演讲者备注：每行使用
```
^ 
```
前缀
图片定位：完全支持所有格式
前置配置：简单的键值对

特性：

使用
```
slidenumbers: true
```
自动添加幻灯片编号
完全控制图片定位
丰富的演讲者备注支持

前置配置示例：

markdown

slidenumbers: true
autoscale: true
theme: Plain Jane, 3

Marp (Optional)

Marp（可选）

Format:

Speaker notes: HTML comments
```

```
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
```
![]()
```

格式：

演讲者备注：使用HTML注释
```

```
图片定位：可能使用不同语法
前置配置：带
```
marp: true
```
的YAML格式

Marp转换示例：

markdown

---
marp: true
paginate: true
---

<!-- 这是Marp中的演讲者备注 -->

差异：

使用HTML注释替代
```
^
```
前缀
不同的前置配置结构
背景图可能需要使用
```
![bg]()
```
而非
```
![]()
```

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

在标记任务完成前，验证以下内容：

无虚构图片——每个图片引用都指向真实文件
所有图片都有有效的URL编码路径
图片文件存在于指定位置（运行
```
ls
```
确认）
路径中的空格已转换为
```
%20
```
特殊字符已正确转义
演讲者备注使用
```
^ 
```
前缀（或Marp使用HTML注释）
演讲者备注放置在每张幻灯片的末尾
幻灯片分隔符(
```
---
```
)位于逻辑断点处
标题层级一致（H1 → H2 → H3）
标题已适当添加表情符号
文件已以
```
- slides
```
后缀保存
保留了源内容的层级结构
无孤立内容或损坏的章节
内部注释已删除
已按要求添加前置配置

Error Handling

错误处理

Missing Images

图片缺失

Problem: Source references image that doesn't exist

Solution:

Check source
```
_files_/
```
directory
Check parent directory
```
_files_/
```
Search for image by name in project
If found: Copy to presentation
```
_files_/
```
directory
If not found: Note in speaker notes and skip image

问题：源内容引用了不存在的图片

解决方案：

检查源文件的
```
_files_/
```
目录
检查父目录的
```
_files_/
```
在项目中按名称搜索图片
如果找到：将图片复制到演示文稿的
```
_files_/
```
目录
如果未找到：在演讲者备注中说明并跳过该图片

Broken Relative Paths

相对路径损坏

Problem: Path doesn't resolve correctly

Solution:

Determine slide file location
Calculate relative path from slide to image
Test path resolution
URL-encode the working path

问题：路径无法正确解析

解决方案：

确定幻灯片文件的位置
计算从幻灯片到图片的相对路径
测试路径解析
对可用路径进行URL编码

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

问题：特殊字符导致图片链接损坏

解决方案：

空格：转换为
```
%20
```
括号：
```
(
```
→
```
%28
```
,
```
)
```
→
```
%29
```
方括号：
```
[
```
→
```
%5B
```
,
```
]
```
→
```
%5D
```
其他特殊字符：使用URL编码

Tips for Best Results

最佳实践提示

Start with outline: Create clear section and slide structure first
One idea per slide: Each slide should have single clear message
Visual hierarchy: Use H1 for sections, H2 for slides, H3 for sub-points
Image positioning: Default to
```
![right fit]()
```
for content slides
Speaker notes: Add context that helps speaker but clutters slide
Emoji consistency: Use similar emojis for similar concepts
Test in Deckset: Preview the slides to verify formatting
Iterate: First pass for structure, second for polish

从大纲开始：先创建清晰的章节和幻灯片结构
每张幻灯片一个核心观点：每张幻灯片应传达单一明确的信息
视觉层级：使用H1表示章节，H2表示幻灯片，H3表示子要点
图片定位：内容幻灯片默认使用
```
![right fit]()
```
演讲者备注：添加对演讲者有帮助但会使幻灯片杂乱的上下文信息
表情符号一致性：相似概念使用相似的表情符号
在Deckset中测试：预览幻灯片以验证格式
迭代优化：第一遍搭建结构，第二遍优化细节