revealjs

Reveal.js 演示文稿

使用 reveal.js 创建 HTML 演示文稿。无需构建步骤，只需在浏览器中打开 HTML 即可。

创建内容

reveal.js 演示文稿由以下部分组成：

1. HTML 文件 - 包含幻灯片，并从 CDN 加载 reveal.js
2. CSS 文件 - 用于布局、颜色、字体排版和组件的自定义样式

设计原则

重要：创建任何演示文稿之前，都要先分析内容并选择合适的设计元素：

1. 考虑主题内容：这份演示文稿的主题是什么？它暗示了怎样的语气、行业或氛围？
2. 检查品牌元素：如果用户提到了公司或组织，请考虑其品牌颜色和形象
3. 使配色与内容相符：选择能体现主题内容的颜色
4. 说明设计思路：编写代码之前，先解释你的设计选择

要求：

• ✅ 编写代码之前，先说明基于内容制定的设计思路
• ✅ 使用适用于 Web 的字体（Arial、Helvetica、Georgia、Verdana 等），或通过 CSS 中的 @import 使用 Google Fonts
• ✅ 通过字号、字重和颜色构建清晰的视觉层次
• ✅ 确保易读性：对比度明显、字号合适、对齐整洁
• ✅ 保持一致：在各张幻灯片中重复使用相同的模式、间距和视觉语言
• ✅ 字体大小始终使用 pt（磅）——幻灯片尺寸固定，因此 pt 可预测且常见（类似 PowerPoint/Keynote）。字体大小不得使用 em、rem 或 px。

配色方案选择

创意地选择颜色：

• 不要局限于默认配色：哪些颜色真正适合这个特定主题？避免不假思索地套用默认配色。
• 从多个角度考虑：主题、行业、氛围、活力程度、目标受众、品牌形象（如有提及）
• 大胆尝试：尝试出人意料的组合——医疗保健演示文稿不一定要用绿色，金融演示文稿也不一定要用海军蓝
• 构建配色方案：选择 3-5 种相互协调的颜色（主色 + 辅助色调 + 点缀色）
• 确保对比度：文字必须在背景上清晰易读

配色方案示例（可从中汲取灵感——选择一种、调整后使用，或创建自己的方案）：

1. 经典蓝：深海军蓝（#1C2833）、板岩灰（#2E4053）、银色（#AAB7B8）、米白色（#F4F6F6）
2. 青绿色与珊瑚色：青绿色（#5EA8A7）、深青绿色（#277884）、珊瑚色（#FE4447）、白色（#FFFFFF）
3. 醒目红色：红色（#C0392B）、亮红色（#E74C3C）、橙色（#F39C12）、黄色（#F1C40F）、绿色（#2ECC71）
4. 暖腮红色调：灰紫色（#A49393）、腮红色（#EED6D3）、玫瑰色（#E8B4B8）、奶油色（#FAF7F2）
5. 酒红奢华风：酒红色（#5D1D2E）、深红色（#951233）、铁锈色（#C15937）、金色（#997929）
6. 深紫与翡翠绿：紫色（#B165FB）、深蓝色（#181B24）、翡翠绿（#40695B）、白色（#FFFFFF）
7. 奶油色与森林绿：奶油色（#FFE1C7）、森林绿（#40695B）、白色（#FCFCFC）
8. 粉色与紫色：粉色（#F8275B）、珊瑚色（#FF574A）、玫瑰色（#FF737D）、紫色（#3D2F68）
9. 青柠绿与李子色：青柠绿（#C5DE82）、李子色（#7C3A5F）、珊瑚色（#FD8C6E）、蓝灰色（#98ACB5）
10. 黑色与金色：金色（#BF9A4A）、黑色（#000000）、奶油色（#F4F6F6）
11. 鼠尾草绿与陶土色：鼠尾草绿（#87A96B）、陶土色（#E07A5F）、奶油色（#F4F1DE）、炭灰色（#2C2C2C）
12. 炭灰色与红色：炭灰色（#292929）、红色（#E33737）、浅灰色（#CCCBCB）
13. 活力橙色：橙色（#F96D00）、浅灰色（#F2F2F2）、炭灰色（#222831）
14. 森林绿：黑色（#191A19）、绿色（#4E9F3D）、深绿色（#1E5128）、白色（#FFFFFF）
15. 复古彩虹色：紫色（#722880）、粉色（#D72D51）、橙色（#EB5C18）、琥珀色（#F08800）、金色（#DEB600）
16. 复古大地色调：芥末黄（#E3B448）、鼠尾草绿（#CBD18F）、森林绿（#3A6B35）、奶油色（#F4F1DE）
17. 海岸玫瑰色调：旧玫瑰色（#AD7670）、河狸棕（#B49886）、蛋壳色（#F3ECDC）、灰绿色（#BFD5BE）
18. 橙色与绿松石色：浅橙色（#FC993E）、灰调绿松石色（#667C6F）、白色（#FCFCFC）

幻灯片内容原则

多样化呈现是关键。 即使幻灯片的内容类型相似，也要改变视觉呈现方式：

• 在不同幻灯片中使用不同的布局：一页使用分栏，另一页使用堆叠框，第三页使用带图标的提示框
• 混合使用不同的容器样式：纯文本、框、提示框、块引用
• 运用视觉层级：使用 <strong> 突出关键术语，用不同颜色区分不同类别
• 使用其他元素（引言、提示框、分栏）拆分列表
• 不要在连续的幻灯片中重复相同的布局模式

保持内容易于浏览：

• 使用简短的项目符号，不要写段落
• 尽可能让每张幻灯片只表达一个主要观点
• 使用图标（Font Awesome）增添视觉趣味

当幻灯片内容较少时，就把内容做大——不要留出大片空白，只放很小的文字。

工作流

步骤 1：规划结构

根据用户提供的内容，确定：

• 需要多少张幻灯片
• 哪些幻灯片应作为章节分隔页（居中显示，文字较大）
• 哪些位置适合使用垂直幻灯片堆栈来逐步展开内容

步骤 2：提取模板

使用 create-presentation.js 脚本（位于与此 SKILL.md 文件相邻的 scripts/ 目录中），从 template.zip 提取并自定义演示文稿模板。

node <path-to-skill>/scripts/create-presentation.js --structure 1,1,d,3,1,d,1 --title "My Presentation" --output-dir ./presentations

查找脚本路径： 脚本位于此 SKILL.md 文件所在位置的相对路径 scripts/create-presentation.js 下。常见位置：

• 项目技能：.claude/skills/revealjs/scripts/create-presentation.js
• 用户技能：~/.claude/skills/revealjs/scripts/create-presentation.js

选项：

• --slides N - 创建 N 张水平幻灯片（简单模式）
• --structure <list> - 使用逗号分隔的值创建混合布局：
  • 1 = 单张水平幻灯片
  • N（其中 N > 1）= N 张幻灯片组成的垂直堆栈
  • d = 章节分隔页（居中显示，无内容容器）
• --output-dir, -o <dir> - 演示文稿文件夹的输出目录（默认：当前目录）
• --title <text> - 演示文稿标题（默认：Presentation）
• --slug <text> - 演示文稿文件夹的自定义 slug（默认：随机十六进制值）

创建的内容： 脚本会将 template.zip 解压到名为 deck-{slug}/ 的文件夹中，其中包含：

• index.html - 演示文稿 HTML 文件
• lib/ - reveal.js 库、插件、字体和 CSS（包含所有依赖项，无需 CDN）
• assets/ - 用于存放图像、文档和其他资源的文件夹（自动创建）

示例：

# 10 horizontal slides in ./presentations directory
node <path-to-skill>/scripts/create-presentation.js --slides 10 --output-dir ./presentations

# Mixed structure: intro, 2 content slides, divider, 3-slide vertical stack, divider, closing
node <path-to-skill>/scripts/create-presentation.js --structure 1,1,1,d,3,d,1 --title "Q4 Review" --output-dir ./decks

# Custom slug
node <path-to-skill>/scripts/create-presentation.js --structure 1,1,1,d,3,d,1,1 --title "My Deck" --slug mydeck

第 3 步：自定义 CSS

模板已在 lib/offline-v2.css 中包含所有必需的 CSS。你可以通过以下方式自定义样式：

1. 直接编辑 lib/offline-v2.css - 此文件包含所有 reveal.js 样式和主题变量
2. 添加自定义 CSS 文件 - 在主样式表之后，将你自己的 CSS 文件链接到 index.html

模板在 lib/fonts/ 中包含本地字体，无需使用 Google Fonts CDN。可用字体包括：

• Montserrat（默认主题字体）
• Overpass、Overpass2
• Lato
• Open Sans
• 以及更多字体（请参阅 lib/fonts/ 目录）

使用 Google Fonts（可选）： 如果你更喜欢 Google Fonts，可在自定义 CSS 文件中添加 @import：

@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@400;600;700&family=Lato:wght@300;400;600&display=swap');

.reveal {
  font-family: "Lato", Helvetica, sans-serif;
}

.reveal h1, .reveal h2, .reveal h3 {
  font-family: "Playfair Display", Georgia, serif;
}

排版指南：

• 字号始终使用 pt（磅） - 幻灯片尺寸固定，因此 pt 大小可预测且易于理解（类似于 PowerPoint/Keynote）
• 正文建议使用约 16-18pt，以确保可读性
• 幻灯片内容较少时，请适当增大字号以填充空间
• 根据层级使用较大的字号（24pt、32pt、48pt）作为标题

自定义 CSS 示例： 在演示文稿文件夹中创建 custom.css 文件，并将其添加到 index.html：

<link rel="stylesheet" type="text/css" href="lib/offline-v2.css">
<link rel="stylesheet" type="text/css" href="custom.css">

然后在 custom.css 中进行自定义：

.reveal .slides section {
  padding: 40px 60px;
  text-align: left;
}

.reveal h1 { font-size: 48pt; }
.reveal h2 { font-size: 36pt; }
.reveal h3 { font-size: 24pt; }
.reveal p, .reveal li { font-size: 16pt; }

重要 - CSS 集成： 创建自定义 CSS 文件（例如 custom.css）后，运行最终化脚本（第 7 步）时，这些文件会自动集成到 lib/offline-v2.css 中。最终化脚本将：

• 将所有自定义 CSS 文件追加到 lib/offline-v2.css
• 从 index.html 中移除外部 CSS 文件引用
• 删除单独的自定义 CSS 文件

这样可以生成单个整合后的 CSS 文件，便于分发。

第 4 步：填写 HTML 内容

编辑演示文稿文件夹中的 index.html 文件，为每张幻灯片添加内容。始终使用 HTML 标记，切勿使用 Markdown（即使模板包含 Markdown 插件）。请遵循以下模式：

标准幻灯片结构：

<section id="unique-slide-id">
  <h2>Slide Title</h2>
  <div class="content">
    
  </div>
</section>

多列布局 - 始终使用内联 CSS 网格（不要创建 .grid-2 之类的实用类）：

<div style="display: grid; grid-template-columns: repeat(2, 1fr); gap: 30px;">
  <div>Column 1</div>
  <div>Column 2</div>
</div>


<div style="display: grid; grid-template-columns: repeat(3, 1fr); gap: 25px;">
  <div>Column 1</div>
  <div>Column 2</div>
  <div>Column 3</div>
</div>


<div style="display: grid; grid-template-columns: 1fr 2fr; gap: 30px;">
  <div>Narrow sidebar</div>
  <div>Wide main content</div>
</div>

为何使用内联样式设置网格？每张幻灯片的布局需求各不相同，例如列比例、间距等。内联样式让你可以单独控制每张幻灯片，而无需创建数十个实用类。

重要 HTML 模式：

• 每个 <section> 都应有唯一的 id 属性，以便稳定识别
• 居中的章节标题幻灯片请使用 class="section-divider"
• 将主要内容包裹在 <div class="content"> 中，以确保间距一致。这是一个 flexbox 容器，会填充标题下方剩余的垂直空间，确保内容正常排布。
• 使用 <div class="footnote"> 在底部添加署名或来源文本

第 5 步：检查内容是否溢出

运行溢出检查器，确保没有幻灯片内容超出边界：

node <path-to-skill>/scripts/check-overflow.js deck-{slug}/index.html

注意： 将 deck-{slug} 替换为实际的演示文稿文件夹名称。

脚本会检查每张幻灯片是否存在：

• 垂直溢出：内容高度超过幻灯片高度
• 水平溢出：内容宽度超过幻灯片宽度

如果检测到溢出，请减少受影响幻灯片的内容或调整字号。

第 6 步：通过截图进行视觉检查

重要：你必须检查每一张幻灯片的截图，一张都不能漏。 不要跳过幻灯片，也不要只检查部分样例。视觉问题很常见，只有逐张检查才能发现。

截取所有幻灯片的截图：

cd deck-{slug}
npx decktape reveal "index.html?export" output.pdf \
  --screenshots \
  --screenshots-directory "screenshots/$(date +%Y%m%d_%H%M%S)"

注意： ?export 查询参数会禁用图表动画，从而使 PDF 渲染效果更清晰。在浏览器中直接查看 HTML 时，图表仍会播放动画。

这会创建带时间戳的文件夹（例如 screenshots/20241210_143052/），方便你追踪版本并比较修复前后的效果。

然后使用 Read 工具检查每个截图图像文件。

需要检查的内容

溢出检测脚本可以捕获大多数布局问题，但以下问题需要目视检查：

1. 容器中的颜色继承：框或提示框内的文本可能会继承父元素的错误颜色。如果页面背景是深色，且文本为浅色，那么浅色 .box 或 .callout 中的文本将难以阅读，除非为该容器明确设置深色文本。

   修复方式——为浅色容器明确设置文本和项目符号颜色：

   .box-light p,
   .box-light li {
     color: var(--text-dark);
   }
   
   .box-light ul li::before {
     background: var(--primary-color);  /* bullet color */
   }
   

2. 自定义项目符号／列表样式：如果覆盖默认列表样式，项目符号在某些容器背景上的对比度可能不足。

3. 图标未显示：如果 Font Awesome 加载失败，图标位置会显示空方块或空白。

4. 溢出的边缘情况：脚本可以捕获大多数溢出，但复杂的嵌套布局偶尔会漏检。

5. 文本换行异常：预期能在一行内显示的文本实际上溢出到两行。这在分栏布局中特别常见：某一栏的标题可能会换行，而其他栏不会，导致版面不齐。

修复后重新截取特定幻灯片：

npx decktape reveal "presentation.html?export" output.pdf \
  --screenshots \
  --screenshots-directory "screenshots/$(date +%Y%m%d_%H%M%S)" \
  --slides 2,5,7-9

然后重新检查更新后的截图，确认问题已修复。新的带时间戳文件夹便于与上一版本进行比较。

第 7 步：完成演示文稿

**重要：**完成演示文稿内容和自定义 CSS 后，必须运行最终处理脚本，以整合样式并清理生成文件。

运行最终处理脚本：

node <path-to-skill>/scripts/finalize.js deck-{slug}

最终处理脚本的作用：

1. 创建 assets/ 文件夹——用于存放图像、文档及其他资源的标准目录（create-presentation.js 也会自动创建该文件夹）
2. 整合自定义 CSS——查找演示文稿根目录中的所有 *.css 文件（lib/offline-v2.css 除外），并：
   • 将其内容附加到 lib/offline-v2.css，并添加清晰的标记
   • 删除独立的 CSS 文件
   • 从 index.html 中删除外部 CSS <link> 标签（仅保留 lib/offline-v2.css）
3. 清理构建文件——删除临时文件：
   • screenshots/ 目录（由 decktape 截图生成流程创建）
   • output.pdf（由 decktape 导出 PDF 时生成）

最终处理的重要性：

• 单个 CSS 文件：所有样式都整合到 lib/offline-v2.css 中，便于分发
• 整洁的 HTML：不再引用外部 CSS，避免移动文件后出错
• 可用于生产环境：删除临时构建文件
• 标准结构：确保存在 assets/ 文件夹，用于整理图像和文档

运行最终处理的时机：

• 完成所有幻灯片内容后
• 添加任何自定义 CSS 文件后
• 分享或部署演示文稿前
• 生成截图／PDF 后（用于清理生成文件）

注意：create-presentation.js 会自动创建 assets/ 文件夹，但如果你要对较早版本的演示文稿执行最终处理，最终处理脚本会确保该文件夹存在。

CSS 组件参考

框

.box {
  background: var(--box-bg);
  border: 1px solid var(--box-border);
  border-radius: 8px;
  padding: 20px;
}

.box-outlined {
  border: 1px solid var(--box-border);
  border-radius: 8px;
  padding: 20px;
  background: transparent;
}

提示框

.callout {
  border-left: 6px solid var(--primary-color);
  padding: 15px 20px;
  margin: 15px 0;
  background: #f9f9f9;
  border-radius: 8px;
}

/* Color variants */
.callout-blue { border-left-color: #2196F3; background: #e3f2fd; }
.callout-orange { border-left-color: #ff9800; background: #fff3e0; }
.callout-green { border-left-color: #4caf50; background: #e8f5e9; }
.callout-gray { border-left-color: #666; background: #f5f5f5; }

引用块

.reveal blockquote {
  border-left: 4px solid var(--primary-color);
  padding-left: 20px;
  margin: 20px 0;
  font-style: italic;
  background: none;
  box-shadow: none;
  width: 100%;
}

.reveal blockquote cite {
  display: block;
  margin-top: 10px;
  font-style: normal;
  color: var(--muted-color);
}

图标（Font Awesome）

模板中已包含 Font Awesome。使用方法：

<i class="fa-solid fa-lightbulb"></i>
<i class="fa-solid fa-check"></i>
<i class="fa-solid fa-gears"></i>

模板结构

template.zip 文件包含从 slides.com 导出的完整 reveal.js 演示文稿，其中包括：

• reveal.js 核心（lib/reveal.js、lib/reveal.css）——演示文稿框架
• 插件（lib/reveal-plugins.js）：
  • RevealZoom——缩放元素（Alt+单击／Ctrl+单击）
  • RevealNotes——演讲者备注视图（按 S）
  • RevealMarkdown——Markdown 支持（可用，但本技能更推荐使用 HTML 标记）
  • RevealHighlight——代码语法高亮
• 字体（lib/fonts/）——供离线使用的本地字体文件
• 样式（lib/offline-v2.css）——包含主题在内的完整 CSS
• 离线支持（lib/offline.js）——无需互联网连接即可使用

**注意：**模板采用 slides.com 格式，但提取时会将其转换为标准 reveal.js <section> 格式。所有插件都已预先配置，可直接使用。

高级功能

有关片段（逐步显示）、演讲者备注、自定义背景、自动动画和过渡效果，请参阅 references/advanced-features.md。

Reveal.js 配置

Reveal.initialize({
  controls: true,          // Show navigation arrows
  progress: true,          // Show progress bar
  slideNumber: true,       // Show slide numbers
  hash: true,              // Update URL hash for each slide
  transition: 'slide',     // none/fade/slide/convex/concave/zoom
  center: false,           // Vertical centering of slide content
  autoSlide: 0,            // Auto-advance (ms), 0 to disable
  loop: false,             // Loop presentation
});

关于 center 的说明： 默认值为 false（内容与顶部对齐），最适合内容较多的幻灯片。对于希望内容垂直居中的简约或创意演示文稿，请设为 true。

内置 Reveal.js 类

无需自定义 CSS，即可直接使用：

• r-fit-text - 自动调整文本大小以填满幻灯片
• r-stretch - 拉伸元素以填满剩余的垂直空间
• r-stack - 将元素叠放在一起

<h1 class="r-fit-text">BIG TEXT</h1>
<img class="r-stretch" src="image.jpg">

添加图表

重要：添加任何图表之前，必须先阅读 references/charts.md。 图表需要特定的 flexbox/grid 布局模式才能正确调整尺寸并避免溢出。未完整阅读文档前，请勿尝试添加图表。

注意： 模板默认不包含 Chart.js。要添加图表，你需要引入 Chart.js 和 reveal.js 图表插件。详情请参阅 references/charts.md。

必需模式 - 图表需要 flexbox 容器，并设置 maintainAspectRatio: false：

<section style="display: flex; flex-direction: column; height: 100%;">
  <h2>Chart Title</h2>
  <div style="flex: 1; position: relative; min-height: 0;">
    <canvas data-chart="bar">
    
    </canvas>
  </div>
</section>

references/charts.md 涵盖以下内容（必读）：

• 布局模式：整张幻灯片、半幅（水平/垂直）、四分之一幅、不等分（1fr 2fr、1fr 3fr）
• 为什么必须采用 flexbox 模式（Chart.js 的纵横比行为）
• 所有图表类型（条形图、折线图、饼图、圆环图、散点图等）
• 样式和颜色选项
• CSV 数据格式（比 JSON 更简单的替代方案）

依赖项

脚本所需依赖：

• Node.js（用于运行脚本）
• adm-zip（用于提取模板）：npm install adm-zip
• cheerio（用于解析 HTML）：npm install cheerio
• Puppeteer（用于检查溢出）：npm install puppeteer
• Decktape（用于截图）：npx decktape（可直接运行）