使用 minorun-marp-skill 打造更出色的 Marp 演示文稿幻灯片

minorun-marp-skill 的作用

minorun-marp-skill 是一组可复用的指南和检查工具，用于使用 Marp 创建演示文稿。它旨在帮助 AI 代理编写不仅视觉整洁，而且故事线清晰、图表实用、设计均衡的幻灯片。

该项目汇集了作者 Minoru Onda 反复使用的演示文稿改进方法，并将其打包成 Claude Code 等 AI 代理可以读取的技能。这些材料也可直接供使用 Marp Markdown 编写演示文稿的人参考。

仓库结构

该仓库将写作指南、视觉设计、主题、验证工具和示例分开组织：

• skills/slide-story 涵盖吸引注意的开场、章节开篇幻灯片、渐进式信息披露、标题风格、结尾，以及演示文稿时长估算。
• skills/slide-figures 介绍如何降低图表的信息密度、绘制 SVG 图形、设置最小文字大小，以及放置插图。
• skills/slide-design-dark 涵盖空白区域测量、垂直平衡、深色背景、表格、代码块，以及 Marp 特有的常见问题。
• theme/minorun-dark.css 提供带青色点缀的深色 Marp 主题。
• tools/ 包含用于测量导出 PDF 和 SVG 输出的脚本。
• examples/sample 包含一个示例演示文稿，而 examples/broken 则有意包含一些问题，用于验证检查工具能否检测到这些问题。

安装与设置

为 Claude Code 复制技能

使用 Claude Code 时，将三个技能目录复制到个人 Claude 技能目录中：

cp -r skills/* ~/.claude/skills/

完成后，Claude Code 就能在帮助你创建或修改幻灯片时使用仓库中的 slide-story、slide-figures 和 slide-design-dark 指南。

将主题和工具复制到幻灯片仓库

将 theme/ 和 tools/ 目录复制到包含演示文稿的仓库中。这样，主题和验证脚本就能与演示文稿所使用的 Markdown 文件及资源放在一起。

安装所需工具

检查脚本依赖 Marp CLI、Google Chrome、poppler、mupdf-tools、Python 3 和 Pillow。使用以下命令安装 Marp CLI：

npm i -g @marp-team/marp-cli

在 macOS 上，使用以下命令安装 PDF 工具：

brew install poppler mupdf-tools

check-svg-box-fit.mjs 使用 Marp CLI 中捆绑的 puppeteer-core。如果无法自动找到其模块或 Chrome 可执行文件，请通过 MARP_NODE_MODULES 和 CHROME_PATH 提供其位置。

准备字体

该主题适用于圆润的哥特体字体。安装 Zen Maru Gothic 可获得推荐的显示效果。在无法使用该字体的 macOS 系统上，主题会改用 Hiragino Maru Gothic 显示。字体是否可用会影响最终演示文稿的外观，因此请在导出幻灯片前安装并验证字体。

创建并导出演示文稿

将幻灯片写入 Marp Markdown 文件，例如 deck.md。使用附带的深色主题和本地文件支持将其导出为 PDF：

marp --no-stdin deck.md --pdf --theme theme/minorun-dark.css --allow-local-files

--theme 选项会应用仓库的深色青色点缀设计。--allow-local-files 选项允许在导出过程中加载演示文稿引用的本地图像及其他资源。

验证导出的幻灯片

导出后，针对生成的 PDF 和所有 SVG 图形运行检查。这些检查用于发现 Markdown 源文件中容易被忽略、但在渲染后的演示文稿中很明显的问题。

检查边距

python3 tools/check-dark-margins.py deck.pdf

该检查会测量幻灯片内容底部和右侧边缘的空白区域。

检查元素之间的间距

python3 tools/check-dark-gaps.py deck.pdf

使用此检查可以找出与相邻文字距离过近的图表或方框。

检查图形中的文字

python3 tools/check-figure-text.py deck.pdf

该检查会查找图形中的小号文字，以及过于靠近方框边缘的文字。

检查 SVG 方框适配

node tools/check-svg-box-fit.mjs images/*.svg

该检查会验证 SVG 方框中的文字是否适合方框尺寸。当图形与幻灯片 Markdown 分开生成或编辑时，此检查尤其有用。

检查复用的幻灯片

python3 tools/check-reuse-diff.py new.md old.md

复用幻灯片时运行此比较工具。它会检查新旧 Markdown 文件中标题与图形之间的关系，帮助你注意到复用的视觉内容是否已不再匹配周围的信息。

添加插图

示例演示文稿经常使用来自 Irasutoya 的插图，但这些图像不包含在仓库中。导出示例演示文稿前，请先下载它们：

sh examples/sample/fetch-illustrations.sh

使用下载的插图前，请自行确认适用的使用条件。示例演示文稿概览中显示的插图是 Irasutoya 的受版权保护作品，不适用本仓库的 Apache License 2.0。

实用的 AI 辅助工作流

1. 从故事开始。 请 AI 代理使用 slide-story 指南，确定开场吸引点、章节过渡、观点的渐进式呈现、标题风格、结尾以及预计演讲时长。
2. 规划图表。 使用 slide-figures 将每个图表精简为观众所需的信息，选择易读的文字大小，并决定使用 SVG 还是插图更合适。
3. 应用视觉系统。 使用 slide-design-dark 和 minorun-dark.css，保持留白、垂直平衡、深色背景下的对比度，以及统一的表格和代码样式。
4. 尽早导出。 使用 Marp 生成 PDF，不要只依赖 Markdown 源文件或编辑器预览。
5. 检查输出。 运行 PDF 和 SVG 检查，然后根据实际渲染问题修改幻灯片，例如图表标签拥挤、间距不足或过度贴近边缘。
6. 整体审阅演讲内容。 确认整套幻灯片具有连贯的推进关系，并确保每个图表都支持所在幻灯片的标题，而不只是起装饰作用。

高级技巧

将有问题的示例用作回归测试

examples/broken 目录有意包含了一套存在问题的幻灯片。使用它确认检查脚本已正确安装，并验证脚本能够响应其设计用于检测的各类布局问题。

验证 PDF，而不只是源 Markdown

Marp 渲染可能会暴露源代码中不明显的问题，包括字体可用性、盒模型尺寸、本地资源以及最终页面布局造成的变化。应将导出的 PDF 视为需要检查的产物。

保持图表文字清晰易读

当图表包含过多信息时，应先删除或延后展示细节，而不是缩小文字。图表指南与 check-figure-text.py 配合使用，可确保图表在现场演示时保持清晰易读。

保持标题与图表一致

如果复用较早的幻灯片，请同时更新标题和视觉说明。复用差异检查有助于发现图表保持不变、但幻灯片信息已经改变的情况。

牢记许可证边界

该仓库以 Apache License 2.0 发布，版权归 Minoru Onda 所有。外部字体和插图可能适用不同条款，因此在分发幻灯片前，请分别核实它们的许可证。

结论

minorun-marp-skill 将面向 Marp 的演示建议转化为可复用的 AI 代理技能、深色主题、示例以及具体的输出检查工具。将这些技能复制到 Claude Code 中，把主题和工具放在幻灯片旁边，使用 Marp 导出，并检查渲染后的 PDF 和 SVG 文件。这套工作流程有助于让叙事、图表和视觉设计协同工作，而不是把幻灯片润色当作最后才考虑的事项。