SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场marp-export

marp-export

办公与效率

查看项目

更新于 10-16 09:16

技能介绍

用途

Marp Export 用于将已存在的 Marp 幻灯片 Markdown 文件导出为 PDF（默认）、HTML、PPTX 或 PNG。它不负责编写幻灯片内容，而是专注于导出流程中的主题加载、浏览器检测与批量转换。

主要能力

  • 多格式导出：PDF（默认）、HTML、PPTX、PNG 序列。
  • 主题加载：通过 --theme-set 加载自定义 CSS 主题。
  • 浏览器检测：PDF/PPTX 导出需要 Chrome/Chromium，必要时可设置 CHROME_PATH。
  • 批量转换：可对目录中的多个 .md 文件循环导出。
  • 可编辑 PPTX：使用 --pptx-editable 输出可编辑 PPTX（需要 LibreOffice）。

需要先了解的两个静默失败

  1. 主题目录错误 → 静默回退。如果文件 frontmatter 中 theme: 指定的主题不在 --theme-set 目录中，marp-cli 不会报错，而是用默认主题渲染，品牌配色、页眉页脚都会丢失。务必根据 frontmatter 中的主题名解析主题目录。
  2. 沙箱内导出 PDF/PPTX → CJK 字形丢失。当 Bash 工具在沙箱中运行时，Chrome 的 printToPDF 无法访问系统中日韩字体：PDF 会“成功”导出，但所有中文/日文/韩文文本都缺失（只剩 ASCII，文件体积明显减小）。PDF 与 PPTX 导出需以 dangerouslyDisableSandbox: true 运行。HTML 与 PNG 导出不受影响。

这两种失败都不会在日志中显现，只有实际渲染产出的 PDF 才能发现。

使用方式

先解析 THEME_DIR，然后执行：

  • PDF（默认，需要 Chrome/Chromium，非沙箱运行）： npx @marp-team/marp-cli INPUT.md -o OUTPUT.pdf --theme-set "$THEME_DIR" --allow-local-files --html
  • HTML： npx @marp-team/marp-cli INPUT.md -o OUTPUT.html --theme-set "$THEME_DIR" --html
  • PPTX（可编辑，需要 LibreOffice，非沙箱运行）： npx @marp-team/marp-cli INPUT.md -o OUTPUT.pptx --pptx-editable --theme-set "$THEME_DIR" --allow-local-files
  • PNG 序列： npx @marp-team/marp-cli INPUT.md --images png -o OUTPUT_DIR/ --theme-set "$THEME_DIR"

工作流分为五步：

  1. 定位输入文件，确认 frontmatter 含 marp: true。
  2. 解析主题目录（不要硬编码）：读取 theme: 名称，在已知主题位置中查找对应 CSS：
    • ~/.claude/skills/marp-slides-creator/themes/：academic、academic-lightblue、beam、border、gradient、jobs、simple、zju 等
    • ~/.claude/skills/marp-slides-lingnan/themes/：lingnan（中山大学岭南学院：深红配色、院徽页脚） 解析命令示例： THEME_NAME=$(sed -n 's/^theme:[[:space:]]//p' INPUT.md | head -1) THEME_DIR=$(grep -rl "@theme $THEME_NAME\b" ~/.claude/skills//themes/.css 2>/dev/null | head -1 | xargs dirname) [ -z "$THEME_DIR" ] && THEME_DIR=$(ls ~/.claude/skills/*/themes/"$THEME_NAME".css 2>/dev/null | head -1 | xargs dirname) 如果 THEME_DIR 为空且主题不是 marp 内置主题（default/gaia/uncover），应停止并定位 CSS。
  3. 检测 Chrome/Chromium（用于 PDF/PPTX）。macOS 可按顺序检查 Google Chrome、Chromium、Microsoft Edge，必要时设置 CHROME_PATH。若没有浏览器，则回退到 HTML 导出并告知用户。
  4. 导出：默认 PDF，输出与输入同目录、同主文件名、不同扩展名（如 presentation.md → presentation.pdf）。PDF 导出需 dangerouslyDisableSandbox: true，HTML 导出沙箱内可运行，PPTX 同样需非沙箱。
  5. 验证与报告：ls -lh 不足以验证，需实际渲染 PDF 页面查看。可用： sips -s format png -z 720 1280 OUTPUT.pdf --out /tmp/pdf_p1.png 或 pdftoppm -png -f N -l N -scale-to-x 1280 -scale-to-y 720 OUTPUT.pdf /tmp/pdf_pN 然后查看 PNG，确认主题样式（品牌配色、页眉页脚）与所有文本（尤其是 CJK）均已渲染。不要用 --images png 输出做验证，因为截图路径在 PDF 缺字形时也能正常渲染。

危险信号：

  • PDF 体积远低于此前正常导出（如同一份幻灯片 1.6M vs 2.7M）→ 缺少嵌入的 CJK 字体。
  • 标题页只剩 ASCII 片段 → 沙箱内导出，需非沙箱重跑。
  • 看起来是默认主题（无品牌配色）→ --theme-set 目录错误，marp 静默回退。

报告内容：输出文件路径、体积、格式；已目视验证的页面；marp-cli 的任何警告。

关键参数

  • --theme-set DIR/：加载自定义主题，存在自定义 .css 主题时使用。
  • --allow-local-files：允许本地图片，PDF/PPTX 含本地资源时使用。
  • --html：允许 markdown 中的 HTML 标签，建议始终添加。
  • --pptx-editable：输出可编辑 PPTX，PPTX 格式使用（需要 LibreOffice）。
  • --images png：导出 PNG 序列，PNG 格式使用。
  • --pdf-notes：在 PDF 中包含演讲者备注，有备注时使用。
  • --pdf-outlines：为 PDF 添加书签，长演示文稿使用。

错误处理

  • Chrome/Chromium not found：PDF 无可用浏览器 → 设置 CHROME_PATH 或回退 HTML。
  • theme not found：缺少主题 CSS → 检查 --theme-set 路径或使用内置主题。
  • Could not find an input：文件路径错误 → 核对路径与 marp: true frontmatter。
  • 空白 PDF：HTML 标签未加 --html → 添加 --html 参数。
  • PDF 缺少全部 CJK 文本（无报错）：沙箱 Chrome 无法读取系统字体 → 以 dangerouslyDisableSandbox: true 重跑。
  • 输出使用默认主题（无报错）：--theme-set 目录中找不到 theme: 名称 → 从 frontmatter 解析 THEME_DIR；例如 lingnan 位于 marp-slides-lingnan，而非 marp-slides-creator。

适用场景

适合将已有 Marp Markdown 幻灯片批量或单份导出为 PDF/HTML/PPTX/PNG，尤其需要自定义主题、本地图片、CJK 文本与可编辑 PPTX 的场景。

限制

  • PDF 与 PPTX 导出依赖 Chrome/Chromium，PPTX 可编辑输出还依赖 LibreOffice。
  • 在沙箱 Bash 环境中导出 PDF/PPTX 会静默丢失 CJK 字体，必须非沙箱运行。
  • 主题名不在 --theme-set 目录时会静默回退默认主题，不报错。
  • 关于收费、价格、平台等信息暂未提供。