astefanutti/decktape

DeckTape

概述

DeckTape 是一个高质量的HTML演示框架PDF导出工具，基于Puppeteer构建，利用Google Chrome进行网页布局和渲染，并通过JavaScript API控制无头Chrome实例。它支持多种主流HTML演示框架，提供通用模式以适应几乎任何框架，并具备插件扩展架构，还可选择捕获不同分辨率的幻灯片截图。

核心功能与特性

• 高质量PDF导出：精确转换HTML演示文稿为PDF格式
• 多框架支持：原生支持多种主流HTML演示框架
• 通用模式：通过模拟用户交互（如按键）支持几乎所有演示框架
• 插件架构：可扩展API，支持添加新框架支持或定制现有插件
• 截图功能：捕获不同分辨率的幻灯片图像，支持JPG/PNG格式
• 灵活配置：支持指定幻灯片范围、视口大小、导出延迟等参数

支持的演示框架

DeckTape 原生支持以下演示框架：

• Bespoke.js
• deck.js
• DZSlides
• https://marcolago.github.io/flowtime.js/
• impress.js
• Inspire.js
• https://github.com/twitwi/nuedeck
• remark
• reveal.js
• https://github.com/damianavila/RISE
• Shower
• Slidy
• https://github.com/jlantunez/webslides

使用场景

• 演讲者将在线或本地HTML演示文稿转换为PDF格式用于分享或打印
• 教育工作者创建演示文稿的PDF讲义
• 开发人员确保响应式演示文稿在不同分辨率下的显示效果
• 需要存档HTML演示文稿为PDF格式的场景

使用方法

Docker镜像获取

DeckTape Docker镜像可从Docker Hub获取：

bash
docker pull astefanutti/decktape

基本命令格式

bash
docker run [选项] astefanutti/decktape [decktape选项] [命令] <演示文稿URL> <输出PDF文件名>

常用选项说明

主要命令

automatic（默认）

自动检测演示文稿使用的框架并选择兼容的插件进行导出。

generic

通过模拟按键交互导出幻灯片，需指定--key选项（默认ArrowRight），适用于不暴露API的框架：

bash
docker run --rm -v $(pwd):/slides astefanutti/decktape generic --key=ArrowDown <URL> slides.pdf

示例

1. 转换在线演示文稿

将在线reveal.js演示转换为PDF并保存到当前目录：

bash
docker run --rm -t -v $(pwd):/slides astefanutti/decktape https://revealjs.com/demos/3.9.2 slides.pdf

2. 转换本地文件

转换本地HTML演示文稿（假设文件位于~/slides.html）：

bash
docker run --rm -t -v $(pwd):/slides -v ~:/home/user astefanutti/decktape /home/user/slides.html slides.pdf

3. 转换本地服务器上的演示文稿

转换运行在本地8000端口的演示文稿：

bash
docker run --rm -t --net=host -v $(pwd):/slides astefanutti/decktape http://localhost:8000 slides.pdf

注意：在macOS和Windows上，可能需要使用host.docker.internal代替localhost。

4. 捕获多分辨率截图

导出PDF的同时捕获400x300和800x600分辨率的截图：

bash
docker run --rm -v $(pwd):/slides astefanutti/decktape --screenshots --screenshots-size=400x300 --screenshots-size=800x600 <URL> slides.pdf

5. 导出指定范围的幻灯片

仅导出第1-3张和第5张幻灯片：

bash
docker run --rm -v $(pwd):/slides astefanutti/decktape --slides 1-3,5 <URL> slides.pdf

导出示例

以下是使用DeckTape导出的演示文稿示例：

常见问题

如何向Chrome传递参数？

使用--chrome-arg选项，例如设置代理：

bash
docker run --rm -v $(pwd):/slides astefanutti/decktape --chrome-arg=--proxy-server="proxy:8080" <URL> slides.pdf

出现"No usable sandbox!"错误怎么办？

某些Linux发行版默认禁用用户命名空间，可临时使用--no-sandbox选项：

bash
docker run --rm -v $(pwd):/slides astefanutti/decktape --chrome-arg=--no-sandbox <URL> slides.pdf

出现CSS规则访问错误怎么办？

Chromium 64+对本地文件或外部样式表的CSS规则访问有CORS限制，可禁用Web安全：

bash
docker run --rm -v $(pwd):/slides astefanutti/decktape --chrome-arg=--disable-web-security <URL> slides.pdf

布局不一致怎么办？

尝试使用-s选项指定特定视口大小，如-s 1024x768：

bash
docker run --rm -v $(pwd):/slides astefanutti/decktape -s 1024x768 <URL> slides.pdf

使用reveal.js时导出永不结束怎么办？

不要在URL中添加?print-pdf或加载打印样式表，DeckTape不依赖reveal.js的内置PDF支持。