用 Markdown 写 Google Slides：deck 工具完全上手

“

“别人花 1 小时排版，我 3 分钟写完就能去喝咖啡。”
如果你也经常被做 PPT 折磨，deck 可能会成为你的新宠。

目录

  1. deck 是什么？
  2. 为什么值得一试：3 个核心亮点
  3. 5 分钟完成安装与授权
  4. 新建或复用现有演示文稿
  5. Markdown → 幻灯片的 3 条规则
  6. 让内容“动”起来：Watch 实时预览模式
  7. 高级玩法：自动布局、代码块转图、CEL 表达式
  8. 常见问题 FAQ（含报错排查）
  9. 小结与下一步

deck 是什么？

一句话概括：deck 让 Google Slides 像写 README 一样简单。
你把想讲的内容写成 Markdown，deck 负责同步到 Google 幻灯片，并保持后续可迭代更新。

传统做法 deck 做法
打开浏览器→拖文本→调字体 写 Markdown→deck apply→完成
想改标题，得翻 10 页 改一行，刷新即见
多人协作版本冲突 Git 管理 Markdown，冲突易解

为什么值得一试：3 个核心亮点

  1. 持续迭代（Continuous Deck Building）
    写完演讲稿，发现要加一页？直接在 Markdown 里插入 --- 新页，再跑 deck apply，Google 幻灯片自动多出对应页，原有排版不动。

  2. 内容与样式彻底分离
    Markdown 只管文字、代码、图片；Google Slides 里的主题、母版、字体颜色继续由设计师掌控。互不干扰。

  3. 命令行友好，天生适合 CI
    一条 deck apply deck.md 就能在 GitHub Actions 里跑，晚上推送，早上同事就能在共享 Drive 里看到最新版。

5 分钟完成安装与授权

“

提前准备：Google 账号、能访问 Google Drive/Slides 的网络环境。

1. 安装 deck

方式 命令
macOS Homebrew brew install deck
任意平台 Go 环境 go install github.com/k1LoW/deck/cmd/deck@latest
二进制 GitHub Releases 下载对应系统文件

安装完成后，终端执行 deck version 能看到版本号即成功。

2. 创建 OAuth 凭据

  1. 打开 Google Cloud Console → 新建或选择项目
  2. API 与服务 > 已启用 API 和服务 → 启用 Google Slides API 和 Google Drive API
  3. 凭据 > 创建凭据 > OAuth 客户端 ID

    • 应用类型选 桌面应用
    • 名称随意，例如 deck-cli
  4. 下载 JSON，重命名为 credentials.json，放到

    • macOS/Linux: ~/.local/share/deck/credentials.json
    • Windows: %USERPROFILE%\.local\share\deck\credentials.json

首次执行 deck ls 会弹出浏览器授权，点击允许即可。授权后会在同目录生成 token.json，以后不再弹窗。

“

如果是 CI/CD，请改用服务账号，步骤见官方文档 docs/setup-service-account.md。

新建或复用现有演示文稿

场景 A：从零创建

deck new talk.md --title "AI 时代的写作革命"
  • 控制台会返回 presentationID，形如 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
  • 同时 talk.md 顶部自动插入 YAML：
---
presentationID: 1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms
title: AI 时代的写作革命
---

场景 B：复用公司模板

deck new talk.md --from 1wIik04tlp1U4SBHTLrSu20dPFlAGTbRHxnqdRFF9nPo --title "AI 时代的写作革命"

--from 后面放母版 ID，这样新建的文件会继承母版的主题、字体、配色。

Markdown → 幻灯片的 3 条规则

规则 1：用 --- 分页

# 封面

副标题

---

## 目录

- 背景
- 方案
- 展望

---

### 背景

正文正文……
  • 三个或以上连字符独占一行即可分页。
  • 出现在文件开头的那条会被忽略，防止首页空白。

规则 2：最小标题当幻灯片标题

Markdown 层级 幻灯片占位符
# 标题（Title）
## 副标题（Subtitle）
其余文本 正文（Body）

示例：

## 分布式系统三要素

### 一致性

所有节点在同一时间具有相同数据。

### 可用性

每次请求都能收到非错的响应。

渲染后，页面标题为“分布式系统三要素”，两个 ### 会按顺序排入正文。

规则 3：注释写备注或页面配置

<!-- {"layout":"section","freeze":true} -->
  • JSON 注释：改布局、冻结页面、跳过导出等
  • 普通注释：演讲者备注

让内容“动”起来：Watch 实时预览模式

写作最怕来回切换窗口。deck 提供了 --watch：

deck apply --watch talk.md

保存文件 1 秒后，浏览器里的幻灯片自动刷新。
和前端开发的热更新一样，写完即见。

高级玩法

1. 自动布局（YAML defaults）

在文稿或全局 ~/.config/deck/config.yml 里写：

defaults:
  - if: page == 1
    layout: title
  - if: headings[2].size() == 1 && bodies.size() == 0
    layout: section-purple
  - if: true
    layout: title-and-body
  • 条件用 CEL 表达式，可判断页码、标题数量、代码块数量等
  • 复杂场景也能一键排版。

2. 代码块转高清图

安装 mermaid-cli：

npm i -g @mermaid-js/mermaid-cli

执行：

deck apply -c 'mmdc -i - -o {{output}} --quiet' talk.md

所有 mermaid 语言的代码块会被渲染成透明底 PNG，再插入幻灯片，放大不失真。

3. 多账号/多环境切换

deck apply talk.md --profile client-a
deck apply talk.md --profile client-b
  • 每个 profile 独立 credentials-client-a.json、token-client-a.json
  • 自由切换，互不串号。

常见问题 FAQ

问题 解决思路
deck apply 报错 403 检查 OAuth 是否添加了测试用户；CI 环境需服务账号并共享演示文稿
图片不显示 确认图片路径或 URL 有效；CI 需公网可访问链接
字体被重置 使用母版主题里的占位符，不要在 deck 生成的文本框手动改
页面顺序错乱 Markdown 里检查 --- 是否独占一行；不要混用 - - - 等符号
想忽略草稿页 在该页顶部加 <!-- {"ignore":true} -->

小结与下一步

deck 把“写 PPT”拆解成两个动作：

  1. 用 Markdown 专注写内容
  2. 用一条命令同步到 Google 幻灯片

如果你已经习惯用 Git 管理文档，用 VS Code 写 Markdown，那么 deck 就是天然的工作流延伸。

下一步可以：

  • 把 deck apply 写进 Makefile，一键 make slides
  • 在 GitHub Actions 里加一步 deck apply --profile ci，让 MR 自动更新预览链接
  • 把公司模板做成 basePresentationID，团队 10 秒即可创建统一风格的新演示文稿

祝你写得轻松，讲得精彩。