Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs: add Windows installation guide and restructure prerequisites

hugohe304fc71d9ce85
diff --git a/README.md b/README.md
index bd73be21..8455ffa9 100644
--- a/README.md
+++ b/README.md
@@ -69,7 +69,27 @@ This project is my attempt to bridge the gap between **domain expertise** and **
### 1. Prerequisites
-**Required:** [Python](https://www.python.org/downloads/) 3.10+ · **Optional:** [Node.js](https://nodejs.org/) 18+ (for WeChat page conversion) · [Pandoc](https://pandoc.org/) (for DOCX/EPUB conversion)
+| Dependency | Required? | What it does | If you skip it |
+|------------|:---------:|--------------|----------------|
+| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **Yes** | Core runtime — everything depends on this | Nothing works |
+| [Node.js](https://nodejs.org/) 18+ | ❌ Optional | Converts WeChat articles and complex web pages to Markdown | You can still use PDF, DOCX, plain text, and simple URLs as source |
+| [Pandoc](https://pandoc.org/) | ❌ Optional | Converts DOCX, EPUB, HTML, LaTeX, RST to Markdown | You can still use PDF, plain text, and URLs as source |
+
+
+> **TL;DR** — Install Python, run `pip install -r requirements.txt`, and you're ready to generate presentations. Install the rest only when you need them.
+
+<details open>
+<summary><strong>Windows</strong> — see the dedicated step-by-step guide ⚠️</summary>
+
+Windows requires a few extra steps (PATH setup, execution policy, etc.). We wrote a **step-by-step guide** specifically for Windows users:
+
+**📖 [Windows Installation Guide](./docs/windows-installation.md)** — from zero to a working presentation in 10 minutes.
+
+Quick version: download Python from [python.org](https://www.python.org/downloads/) → **check "Add to PATH"** during install → `pip install -r requirements.txt` → done.
+</details>
+
+<details>
+<summary><strong>macOS / Linux</strong> — install and go</summary>
```bash
# macOS
@@ -77,13 +97,12 @@ brew install python
brew install node # optional — for WeChat page conversion
brew install pandoc # optional — for DOCX/EPUB conversion
-# Ubuntu/Debian
+# Ubuntu / Debian
sudo apt install python3 python3-pip
sudo apt install nodejs npm # optional
sudo apt install pandoc # optional
-
-# Windows — download from python.org, nodejs.org, pandoc.org
```
+</details>
### 2. Pick an AI Editor
@@ -169,6 +188,7 @@ Run `python3 skills/ppt-master/scripts/image_gen.py --list-backends` to see tier
| | Document | Description |
|---|----------|-------------|
| 🆚 | [Why PPT Master](./docs/why-ppt-master.md) | How it compares to Gamma, Copilot, and other AI tools |
+| 🪟 | [Windows Installation](./docs/windows-installation.md) | Step-by-step setup guide for Windows users |
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | Core workflow and rules |
| 📐 | [Canvas Formats](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9, Xiaohongshu, WeChat, and 10+ formats |
| 🛠️ | [Scripts & Tools](./skills/ppt-master/scripts/README.md) | All scripts and commands |
diff --git a/README_CN.md b/README_CN.md
index 51ec7530..0450ed13 100644
--- a/README_CN.md
+++ b/README_CN.md
@@ -69,7 +69,27 @@ PPT Master 源于一个真实的痛点:在投融资和咨询工作中,我每
### 1. 前置条件
-**必需:** [Python](https://www.python.org/downloads/) 3.10+ · **可选:** [Node.js](https://nodejs.org/) 18+(微信公众号转换)· [Pandoc](https://pandoc.org/)(DOCX/EPUB 转换)
+| 依赖项 | 是否必需 | 作用 | 不装会怎样 |
+|--------|:--------:|------|-----------|
+| [Python](https://www.python.org/downloads/) 3.10+ | ✅ **必需** | 核心运行时——一切都依赖它 | 什么都跑不了 |
+| [Node.js](https://nodejs.org/) 18+ | ❌ 可选 | 将微信公众号文章、复杂网页转换为 Markdown | 仍可用 PDF、DOCX、纯文本、简单 URL 作为素材 |
+| [Pandoc](https://pandoc.org/) | ❌ 可选 | 将 DOCX、EPUB、HTML、LaTeX、RST 转换为 Markdown | 仍可用 PDF、纯文本、URL 作为素材 |
+
+
+> **一句话总结** — 装好 Python,跑一行 `pip install -r requirements.txt`,就可以开始生成 PPT 了。其余的用到时再装。
+
+<details open>
+<summary><strong>Windows</strong> — 请看专门的手把手安装指南 ⚠️</summary>
+
+Windows 需要一些额外步骤(PATH 设置、执行策略等)。我们为 Windows 用户写了一份**手把手安装指南**:
+
+**📖 [Windows 安装指南](./docs/zh/windows-installation.md)** — 从零到跑通第一份 PPT,10 分钟搞定。
+
+简要流程:从 [python.org](https://www.python.org/downloads/) 下载 Python → **安装时勾选 "Add to PATH"** → `pip install -r requirements.txt` → 完成。
+</details>
+
+<details>
+<summary><strong>macOS / Linux</strong> — 安装即用</summary>
```bash
# macOS
@@ -77,13 +97,12 @@ brew install python
brew install node # 可选——用于微信公众号等网页转换
brew install pandoc # 可选——用于 DOCX/EPUB 转换
-# Ubuntu/Debian
+# Ubuntu / Debian
sudo apt install python3 python3-pip
sudo apt install nodejs npm # 可选
sudo apt install pandoc # 可选
-
-# Windows — 从 python.org、nodejs.org、pandoc.org 下载安装
```
+</details>
### 2. 选择 AI 编辑器
@@ -173,6 +192,7 @@ GEMINI_MODEL=gemini-3.1-flash-image-preview
| | 文档 | 说明 |
|---|------|------|
| 🆚 | [为什么选 PPT Master](./docs/zh/why-ppt-master.md) | 与 Gamma、Copilot 等工具的对比 |
+| 🪟 | [Windows 安装指南](./docs/zh/windows-installation.md) | Windows 用户手把手安装教程 |
| 📖 | [SKILL.md](./skills/ppt-master/SKILL.md) | 核心流程与规则 |
| 📐 | [画布格式](./skills/ppt-master/references/canvas-formats.md) | PPT 16:9、小红书、朋友圈等 10+ 种格式 |
| 🛠️ | [脚本与工具](./skills/ppt-master/scripts/README.md) | 所有脚本和命令 |
diff --git a/docs/windows-installation.md b/docs/windows-installation.md
new file mode 100644
index 00000000..98ec0f20
--- /dev/null
+++ b/docs/windows-installation.md
@@ -0,0 +1,151 @@
+# Windows Installation Guide
+
+This guide walks you through installing PPT Master on Windows step by step. Follow along and you'll have a working setup in under 10 minutes.
+
+---
+
+## Step 1 — Install Python (Required)
+
+Python is the only hard requirement.
+
+1. Go to **[python.org/downloads](https://www.python.org/downloads/)** and download the latest **Python 3.10+** installer.
+
+2. **⚠️ CRITICAL: Check "Add python.exe to PATH"** during installation — this is the single most common mistake on Windows. Skipping this will break every step that follows.
+
+ ![Python installer — check Add to PATH](assets/windows-python-path.png)
+
+3. After installation, open **PowerShell** (search "PowerShell" in Start menu) and verify:
+
+ ```powershell
+ python --version
+ ```
+
+ You should see `Python 3.12.x` or similar. If you see "Python was not found" or it opens the Microsoft Store, see [Troubleshooting](#python-was-not-found-or-opens-microsoft-store) below.
+
+> **💡 Tip**: Python installed via Anaconda or Miniconda works too — just make sure `python --version` shows 3.10+.
+
+---
+
+## Step 2 — Download the Project
+
+**Option A — Download ZIP** (easiest):
+
+1. Go to [github.com/hugohe3/ppt-master](https://github.com/hugohe3/ppt-master)
+2. Click the green **Code** button → **Download ZIP**
+3. Unzip to `C:\Users\YourName\ppt-master`
+
+**Option B — Git Clone** (requires [Git](https://git-scm.com/downloads)):
+
+```powershell
+git clone https://github.com/hugohe3/ppt-master.git
+cd ppt-master
+```
+
+---
+
+## Step 3 — Install Dependencies
+
+```powershell
+cd C:\Users\YourName\ppt-master # ← adjust to your actual path
+pip install -r requirements.txt
+```
+
+> If `pip` is not recognized, try `python -m pip install -r requirements.txt`.
+
+Wait for it to finish. You should see `Successfully installed ...` at the end.
+
+---
+
+## Step 4 — Verify Your Setup
+
+```powershell
+python -c "import pptx; import fitz; print('All core dependencies OK')"
+```
+
+✅ Output: `All core dependencies OK` → you're good.
+
+❌ Error → see [Troubleshooting](#troubleshooting) below.
+
+---
+
+## Step 5 — Run a Minimal Example
+
+Open your AI editor (Cursor, VS Code + Copilot, etc.), open the `ppt-master` folder, and type in the chat:
+
+```
+Please create a simple 3-page test PPT with a cover, one content page, and a closing page. Topic: "Hello World".
+```
+
+If a `.pptx` file appears in `exports/` that opens in PowerPoint — **you're done.**
+
+---
+
+## Step 6 — Optional Dependencies (install when needed)
+
+| Dependency | How to install | Verify |
+|------------|----------------|--------|
+| **Node.js** — WeChat articles / complex web pages | Download LTS from [nodejs.org](https://nodejs.org/) | `node --version` → v18+ |
+| **Pandoc** — DOCX / EPUB conversion | Download `.msi` from [pandoc.org](https://pandoc.org/installing.html) | `pandoc --version` |
+| **CairoSVG** — higher quality PNG fallbacks | Install [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases), then `pip install cairosvg` | `python -c "import cairosvg"` |
+
+> Skip CairoSVG if unsure. PPT Master auto-falls back to `svglib` (already installed via `requirements.txt`), which works fine for most cases.
+
+---
+
+## Troubleshooting
+
+### `python` was not found or opens Microsoft Store
+
+**Cause**: Python isn't in your system PATH.
+
+**Fix 1** — Re-run the Python installer → **Modify** → check **"Add Python to environment variables"**.
+
+**Fix 2** — Manually add to PATH:
+1. Run `where python` in PowerShell first to find the actual path (e.g. `C:\Users\YourName\AppData\Local\Programs\Python\Python312\python.exe`)
+2. Search "Environment Variables" in Start menu
+3. Find `Path` → **Edit** → add the **directory** from step 1 and its `Scripts` subfolder:
+ ```
+ C:\Users\YourName\AppData\Local\Programs\Python\Python312
+ C:\Users\YourName\AppData\Local\Programs\Python\Python312\Scripts
+ ```
+4. Click OK, then **restart PowerShell**
+
+**Fix 3** — Try `python3` or `py` instead.
+
+### `pip install` fails with permission errors
+
+```powershell
+pip install --user -r requirements.txt
+```
+
+Or run PowerShell as Administrator.
+
+### `pip install` fails due to network issues
+
+```powershell
+pip install -r requirements.txt --proxy http://your-proxy:port
+```
+
+### `ModuleNotFoundError`
+
+`pip` installed to a different Python. Use `python -m pip install -r requirements.txt` to match.
+
+### `import fitz` fails
+
+1. Upgrade pip: `python -m pip install --upgrade pip`
+2. Pre-built wheel: `pip install PyMuPDF --only-binary :all:`
+3. Still failing → install [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+
+### PowerShell says "running scripts is disabled"
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+---
+
+## Still stuck?
+
+- 📖 [FAQ](./faq.md)
+- 🐛 [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) — include your Python version, Windows version, and full error message
+- 💬 [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)
diff --git a/docs/zh/windows-installation.md b/docs/zh/windows-installation.md
new file mode 100644
index 00000000..0908b46a
--- /dev/null
+++ b/docs/zh/windows-installation.md
@@ -0,0 +1,158 @@
+# Windows 安装指南
+
+本指南将手把手教你在 Windows 上安装 PPT Master。按顺序操作,10 分钟内即可跑通第一份 PPT。
+
+---
+
+## Step 1 — 安装 Python(必须)
+
+Python 是唯一的硬性要求。
+
+1. 前往 **[python.org/downloads](https://www.python.org/downloads/)**,下载最新的 **Python 3.10+** 安装包。
+
+2. **⚠️ 关键步骤:安装时务必勾选 "Add python.exe to PATH"** — 这是 Windows 上最常见的安装失误,不勾的话后面每一步都会出问题。
+
+ ![Python 安装器 — 勾选 Add to PATH](../assets/windows-python-path.png)
+
+3. 安装完成后,打开 **PowerShell**(在开始菜单搜索「PowerShell」)并验证:
+
+ ```powershell
+ python --version
+ ```
+
+ 应该看到 `Python 3.12.x` 之类的输出。如果提示「未找到」或弹出 Microsoft Store,见下方[常见问题](#python-未找到或弹出-microsoft-store)。
+
+> **💡 提示**:Anaconda / Miniconda 安装的 Python 也可以用,只要 `python --version` 显示 3.10+ 即可。
+
+---
+
+## Step 2 — 下载项目
+
+**方式 A — 下载 ZIP**(最简单):
+
+1. 打开 [GitHub](https://github.com/hugohe3/ppt-master)(或 [AtomGit 镜像](https://atomgit.com/hugohe3/ppt-master),国内更快)
+2. 点击绿色 **Code** 按钮 → **Download ZIP**
+3. 解压到 `C:\Users\你的用户名\ppt-master`
+
+**方式 B — Git Clone**(需要 [Git](https://git-scm.com/downloads)):
+
+```powershell
+# GitHub
+git clone https://github.com/hugohe3/ppt-master.git
+# AtomGit(国内更快)
+git clone https://atomgit.com/hugohe3/ppt-master.git
+cd ppt-master
+```
+
+---
+
+## Step 3 — 安装依赖
+
+```powershell
+cd C:\Users\你的用户名\ppt-master # ← 替换为你的实际路径
+pip install -r requirements.txt
+```
+
+> 如果 `pip` 无法识别,用 `python -m pip install -r requirements.txt`。
+
+等待安装完成,最后看到 `Successfully installed ...` 就行。
+
+---
+
+## Step 4 — 验证安装
+
+```powershell
+python -c "import pptx; import fitz; print('All core dependencies OK')"
+```
+
+✅ 输出 `All core dependencies OK` → 核心环境没问题。
+
+❌ 报错 → 见下方[常见问题](#常见问题)。
+
+---
+
+## Step 5 — 跑一个最小示例
+
+打开你的 AI 编辑器(Cursor、VS Code + Copilot 等),打开 `ppt-master` 目录,在聊天面板输入:
+
+```
+请创建一个 3 页测试 PPT,封面 + 内容页 + 封底,主题"Hello World"
+```
+
+`exports/` 下出现 `.pptx` 且能在 PowerPoint 中打开 → **搞定了。**
+
+---
+
+## Step 6 — 可选依赖(用到时再装)
+
+| 依赖 | 安装方式 | 验证 |
+|------|---------|------|
+| **Node.js** — 微信公众号 / 复杂网页转换 | [nodejs.org](https://nodejs.org/) 下载 LTS 版安装 | `node --version` → v18+ |
+| **Pandoc** — DOCX / EPUB 转换 | [pandoc.org](https://pandoc.org/installing.html) 下载 `.msi` 安装 | `pandoc --version` |
+| **CairoSVG** — 更高质量 PNG 后备图 | 安装 [GTK3 Runtime](https://github.com/nickvdp/gtk3/releases) 后 `pip install cairosvg` | `python -c "import cairosvg"` |
+
+> CairoSVG 不确定就跳过。PPT Master 会自动用 `svglib`(已随 `requirements.txt` 安装),大多数情况够用。
+
+---
+
+## 常见问题
+
+### `python` 未找到或弹出 Microsoft Store
+
+**原因:** Python 没有加入系统 PATH。
+
+**方法 1** — 重新运行 Python 安装程序,选择 **Modify**,确保勾选 **"Add Python to environment variables"**。
+
+**方法 2** — 手动添加 PATH:
+1. 先在 PowerShell 中运行 `where python`,记下输出的路径(如 `C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\python.exe`)
+2. 开始菜单搜索「环境变量」
+3. 找到 `Path` → **编辑** → 新增上面路径的**目录部分**及其 `Scripts` 子目录:
+ ```
+ C:\Users\你的用户名\AppData\Local\Programs\Python\Python312
+ C:\Users\你的用户名\AppData\Local\Programs\Python\Python312\Scripts
+ ```
+4. 确定,**重启 PowerShell**
+
+**方法 3** — 试试 `python3` 或 `py` 命令。
+
+### `pip install` 报权限错误
+
+```powershell
+pip install --user -r requirements.txt
+```
+
+或以管理员身份运行 PowerShell。
+
+### `pip install` 网络问题
+
+```powershell
+# 清华镜像(国内推荐)
+pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
+
+# 代理
+pip install -r requirements.txt --proxy http://your-proxy:port
+```
+
+### `ModuleNotFoundError`
+
+`pip` 装到了另一个 Python 环境。用 `python -m pip install -r requirements.txt` 确保对应同一个。
+
+### `import fitz` 失败
+
+1. 升级 pip:`python -m pip install --upgrade pip`
+2. 预编译包:`pip install PyMuPDF --only-binary :all:`
+3. 仍失败 → 安装 [Visual C++ Build Tools](https://visualstudio.microsoft.com/visual-cpp-build-tools/)
+
+### PowerShell「脚本运行被禁用」
+
+```powershell
+Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
+```
+
+---
+
+## 还是搞不定?
+
+- 📖 [常见问题 (FAQ)](./faq.md)
+- 🐛 [GitHub Issues](https://github.com/hugohe3/ppt-master/issues) — 附上 Python 版本、Windows 版本和完整报错
+- 💬 [GitHub Discussions](https://github.com/hugohe3/ppt-master/discussions)