markdown-slides

Markdown 幻灯片技能

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

何时使用此技能

在用户执行以下操作时启用此技能：

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

输入要求

• 源内容：Markdown 文件、大纲或结构化内容
• 图片：_files_/ 目录中的文件或需要解析的路径
• 目标平台：Deckset（默认）或 Marp
• 选项：
  • 演讲者备注（默认启用）
  • 幻灯片编号（可选的 frontmatter）
  • Emoji 增强（默认启用）

输出规范

• 文件位置：与源文件位于同一文件夹
• 文件命名：原文件名加上 - slides 后缀
  • 示例：document.md → document - slides.md
• 格式：兼容 Deckset 的 Markdown
• 结构：包含恰当的幻灯片分隔符、图片标签和演讲者备注
• 增强：添加 Emoji，使视觉效果更佳

主要流程

步骤 1：设置幻灯片结构

目标：创建逻辑清晰、层次恰当的幻灯片划分

操作：

1. 阅读并分析源内容结构
2. 在逻辑分界处插入幻灯片分隔符（---）：
   • 在主要章节之间
   • 在不同主题之间
   • 在章节介绍幻灯片之后
   • 在主要示意图之前或之后
3. 保持内容层次结构：
   • H1（#）用于章节标题
   • H2（##）用于主要幻灯片标题
   • H3（###）用于子主题
4. 保留原有组织结构和行文顺序
5. 添加可选的 frontmatter：slidenumbers: true

示例：

slidenumbers: true
# 1. Section Title 🎯

![](section-background.png)

^ Introduction to this section.

---

## Main Topic 📊

Content here...

---

### Detailed Subtopic

More details...

步骤 2：转换图片格式

目标：将图片转换为 Deckset 格式，并正确设置位置

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

图片位置格式：

格式	用途	示例
![]()	章节介绍背景	
![inline]()	文本流中的示意图	
![right fit]()	主要用途：内容幻灯片	
![right 80%]()	需要特定尺寸时	
![inline fill]()	全宽行内图片	

操作：

1. 找出源文件中的所有图片引用
2. 对每张图片：

   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. 根据上下文设置位置：
   • 章节介绍：使用 ![]() 设置全屏背景
   • 文本中的示意图：使用 ![inline]()
   • 内容幻灯片的默认设置：使用 ![right fit]() ⭐
   • 自定义尺寸：需要时使用 ![right XX%]()
   • 全宽行内图片：宽幅图片使用 ![inline fill]()

示例：

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

步骤 3：转换演讲者备注

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

格式：以 ^ （插入符号 + 空格）开头的行

位置：每张幻灯片的末尾

转换为演讲者备注： ✅ 多句段落 ✅ 说明性文字 ✅ 补充背景信息 ✅ 演讲要点

不要转换： ❌ 单句段落 ❌ 列表（项目符号或编号） ❌ 引用块 ❌ 以冒号（:）结尾的句子 ❌ 标题（H1、H2、H3） ❌ 表格内容

对于 Marp 平台：改用 HTML 注释

示例：

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

第 4 步：内容优化

目标：润色呈现效果，发挥最大影响力

操作：

1. 为标题添加表情符号，包括章节标题和幻灯片标题：

   • 使用能增强含义的相关表情符号
   • 不要过度使用，保持专业
   • 示例：🎯📊🤖💡🚀📚🔧⚡

2. 清理注释：

   • 删除不用于幻灯片的 Markdown 注释
   • 删除 TODO 项
   • 删除内部备注

3. 确保格式整洁：

   • 间距一致
   • 标题层级规范
   • 幻灯片分隔清晰

4. 添加 frontmatter（如有要求）：

   slidenumbers: true
   

5. 最终检查：

   • 每张幻灯片都有明确重点
   • 图片位置正确
   • 演讲者备注置于末尾
   • 没有悬置内容

关键指南

图片处理

⚠️ 关键规则：

1. 绝不虚构图片——仅引用源文档或 _files_/ 文件夹中已有的图片。不要为不存在的图片创建诸如 background-xxx.png 的占位引用。
2. 有原图时使用原图
3. 将缺失的图片复制到 _files_/ 目录，而不是替换图片
4. 逐张解析路径——不要假定所有图片都在同一目录
5. 对空格进行 URL 编码：my file.png → my%20file.png
6. 转义特殊字符：
   • 圆括号：( → %28，) → %29
   • 其他特殊字符也需按需转义
7. 引用前确认图片存在——运行 ls 或 glob 命令确认文件存在
8. 保持语义相关——图片应与幻灯片内容相符
9. 章节引言可以不配图片——如果章节引言幻灯片没有背景图片，只需使用标题和演讲者备注，不要添加图片引用

图片位置标准

图片位置决策树：

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

演讲者备注规则

应转换为演讲者备注的内容：

• 多句解释性段落
• 幻灯片上不需要的背景信息
• 演讲者的要点
• 用于口头讲解的补充细节

不应转换的内容：

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

格式：

Slide content here.

^ Speaker note paragraph one. Can be multiple sentences providing context.

^ Speaker note paragraph two. Each note paragraph gets its own ^ prefix.

内容规范

1. 文件命名：

   • 始终使用 - slides 后缀
   • 其他部分保留原文件名
   • 示例：AI for PKM.md → AI for PKM - slides.md

2. 表情符号用法：

   • 为 H1 和 H2 标题添加表情符号
   • 选择相关且专业的表情符号
   • 不要过度使用——重质量而非数量
   • 示例：
     • 🎯 目标／目的
     • 📊 数据／图表
     • 🤖 AI／技术
     • 💡 想法／见解
     • 🚀 未来／发布
     • 📚 学习／知识

3. 层级：

   • H1 用于主要章节（通常带编号）
   • H2 用于主要幻灯片标题
   • H3 用于幻灯片内的子主题
   • 编号方案保持一致

4. 幻灯片分隔：

   • 独占一行使用 ---（三个连字符）
   • 建议在前后留空行
   • 在主题之间合理分隔

平台专用说明

Deckset（默认）

格式：

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

功能：

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

Frontmatter 示例：

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

Marp（可选）

格式：

• 演讲者备注：HTML 注释 ``
• 图片位置：可能使用不同语法
• Frontmatter：包含 marp: true 的 YAML

转换为 Marp：

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

差异：

• 使用 HTML 注释，而不是 ^ 前缀
• Frontmatter 结构不同
• 可能需要使用 ![bg]() 作为背景，而不是 ![]()

质量检查清单

标记任务完成前，请确认：

• 不添加虚构图片 —— 每个图片引用都指向真实文件
• 所有图片都使用有效的 URL 编码路径
• 图片文件位于指定位置（运行 ls 确认）
• 路径中的空格已转换为 %20
• 特殊字符已正确转义
• 演讲者备注使用 ^ 前缀（或在 Marp 中使用 HTML）
• 演讲者备注位于每张幻灯片的末尾
• 幻灯片分隔符（---）位于合理的分隔处
• 标题层级一致（H1 → H2 → H3）
• 为标题适当添加表情符号
• 文件已使用 - slides 后缀保存
• 保持源内容的层级结构
• 没有孤立内容或不完整的部分
• 已移除内部注释
• 如果有要求，已添加 Frontmatter

错误处理

图片缺失

问题：源文件引用了不存在的图片

解决方案：

1. 检查源文件的 _files_/ 目录
2. 检查上级目录中的 _files_/ 目录
3. 在项目中按名称搜索图片
4. 如果找到：复制到演示文稿的 _files_/ 目录
5. 如果未找到：在演讲者备注中注明并跳过该图片

相对路径失效

问题：路径无法正确解析

解决方案：

1. 确定幻灯片文件的位置
2. 计算幻灯片到图片的相对路径
3. 测试路径是否可解析
4. 对可用路径进行 URL 编码

路径中的无效字符

问题：特殊字符导致图片链接失效

解决方案：

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

最佳实践提示

1. 从大纲开始：先创建清晰的章节和幻灯片结构
2. 每张幻灯片只讲一个要点：每张幻灯片都应传达一个明确的信息
3. 视觉层级：章节使用 H1，幻灯片使用 H2，子要点使用 H3
4. 图片位置：内容幻灯片默认使用 ![right fit]()
5. 演讲者备注：添加有助于演讲者、但会让幻灯片显得杂乱的背景信息
6. 统一表情符号：为相似概念使用相似的表情符号
7. 在 Deckset 中测试：预览幻灯片以检查格式
8. 反复调整：第一轮确定结构，第二轮润色