用户使用帮助

Presto 是一款桌面应用，让你用 Markdown 写内容、选一个模板，一键生成排版精美的 PDF 文档。不需要学排版软件，不需要手动调格式——写好内容，剩下的交给 Presto。

---

第一部分：安装

各平台的命令行快速安装方式：

macOS (Homebrew)

brew install --cask brewforge/more/presto

Linux

# 从 GitHub Releases 下载最新版
curl -sL https://github.com/mrered/Presto/releases/latest/download/Presto-linux-amd64.tar.gz | tar -xz
./Presto

Windows 用户请直接下载安装程序，详见下方 Windows 安装 章节。

如需手动安装或遇到问题，请参考下方各平台的详细说明。

macOS 安装

macOS 提供两种安装方式，任选其一。

最低系统要求：macOS 11.0 (Big Sur) 及以上。

方式一：通过 Homebrew 安装（推荐）

如果你的 Mac 上已经装了 Homebrew（一个常用的软件管理工具），在终端中运行：

brew install --cask brewforge/more/presto

安装完成后，打开 Launchpad（启动台），看到 Presto 图标就说明安装成功了。

方式二：手动下载安装

1. 打开 GitHub Releases 页面，下载最新的 .dmg 文件
2. 双击打开 DMG 文件
3. 把 Presto 图标拖到 Applications（应用程序）文件夹中

重要：解除 macOS Gatekeeper 拦截

首次打开 Presto 时，macOS 可能会弹出提示："无法验证开发者"或"无法打开，因为无法验证其是否包含恶意软件"。

这不是因为 Presto 有问题。原因是：macOS 的 Gatekeeper 安全机制要求应用必须经过 Apple 认证（需要开发者加入 Apple Developer Program，每年 99 美元）。Presto 目前使用的是 ad-hoc 签名（自签名），功能和安全性没有任何区别，只是还没有向 Apple 付费认证。

解决方法（二选一）：

方法 A：终端命令（推荐，一劳永逸）

打开"终端"应用（在 Launchpad 中搜索"终端"），粘贴以下命令并按回车：

xattr -cr /Applications/Presto.app

这条命令的作用是移除系统给 Presto 打上的"未验证"标记。运行后就可以正常打开了。

方法 B：右键打开

1. 在 Applications 文件夹中找到 Presto
2. 按住 Control 键点击（或右键点击）Presto 图标
3. 在弹出菜单中选择"打开"
4. 在弹出的对话框中再次点击"打开"

Windows 安装

1. 打开 GitHub Releases 页面，下载最新的 Windows 安装程序（.exe）
2. 双击安装程序，按提示完成安装
3. 安装完成后，从桌面或开始菜单打开 Presto

Windows 安装程序只安装主程序、Typst 和必要运行库。首次启动时，Presto 会从模板注册中心下载官方模板；如果网络失败，可以稍后打开"模板商店"重新安装。

注意：首次运行时，Windows SmartScreen 可能会弹出蓝色警告窗口。这和 macOS 的情况类似——因为应用没有购买商业代码签名证书。点击"更多信息"，然后点击"仍要运行"即可。

卸载 Presto 时，Windows 卸载程序会询问是否同时删除 %USERPROFILE%\.presto。选择删除会清理模板、字体和注册中心缓存；选择保留则重新安装后仍可继续使用这些本地数据。

Linux 安装

1. 打开 GitHub Releases 页面，下载最新的 .tar.gz 文件

2. 解压文件：

   tar -xzf Presto-linux-*.tar.gz

3. 运行 Presto：

   ./Presto

Docker 部署（Web 端）

本节面向有一定技术基础的用户。Docker 部署提供 Web 版 Presto，适合团队共享或服务器部署。

快速启动：

mkdir -p .presto-data/fonts
docker compose up -d

或使用预构建镜像：

docker run -d -p 8080:8080 \
  -v "$PWD/.presto-data/fonts:/home/presto/.presto/fonts" \
  ghcr.io/presto-io/presto

启动后访问 http://localhost:8080 即可使用。

默认的 Docker Compose 配置会把本地 ./.presto-data/fonts 挂载到容器内的 /home/presto/.presto/fonts。需要安装模板依赖字体时，把 .ttf、.otf、 .ttc 或 .otc 字体文件放进 ./.presto-data/fonts，然后重启服务：

docker compose restart presto

如果 .presto-data 曾由 root 或其他用户创建，先修正目录权限：

sudo chown -R "$(id -u):$(id -g)" .presto-data

生产环境如果需要 HTTPS，请在 Presto 前面接入 Caddy、Nginx、Traefik 或平台自带的反向代理。

macOS / Linux 本地数据清理标记

Presto 会把下载的模板、字体、注册中心缓存等运行时数据放在 ~/.presto。为了让清理工具更容易识别这些文件，Presto 会在该目录中写入 .presto-generated.json 和 .presto-cleanup.txt，标记这些内容由 com.mrered.presto 生成且卸载后可删除。

macOS 会额外在 ~/Library/Application Support/com.mrered.presto/ 记录 ~/.presto 的位置；Linux 会在 $XDG_DATA_HOME/com.mrered.presto/ 或 ~/.local/share/com.mrered.presto/ 记录位置，并尽量写入 user.xdg.* 扩展属性。如果清理软件没有自动处理，也可以手动删除 ~/.presto 来清理模板、字体和缓存。

---

第二部分：基本使用

核心工作流

1. 打开 Presto，你会看到一个左右分栏的界面

2. 在左侧编辑器中编写你的文档内容（使用 Markdown 语法，支持语法高亮）

3. 点击顶部的下拉菜单，选择一个模板

4. 右侧会实时显示排版后的预览效果（多页 SVG 渲染，左右两侧滚动同步）

5. 按 Cmd+E（macOS）或 Ctrl+E（Windows/Linux）导出 PDF

YAML Front Matter

Frontmatter 是写在文档最顶部、用 --- 包裹的元数据区域。它告诉模板这篇文档的基本信息。

• template 字段用于自动匹配模板，如果你在 frontmatter 中指定了模板名称，Presto 会自动选中它
• 模板特有字段（如 title、author、date 等）由每个模板自行定义，具体支持哪些字段请参考官方模板使用说明

以下是 gongwen（公文）模板的 frontmatter 示例：

---
template: gongwen
title: 关于开展安全检查的通知
author: 办公室
date: "2025-03-15"
signature: true
---

内置模板

Presto 自带两个模板，安装后即可使用：

• gongwen — 类公文模板，遵循 GB/T 9704-2012 风格，适合通知、报告、函件等正式文档
• jiaoan-shicao — 实操教案表格模板，适合教学计划、实验报告等表格类文档

详细 Markdown 写法见官方模板使用说明。

---

第三部分：模板管理

安装模板

Presto 支持 5 种方式安装新模板：

1. 模板商店 — 打开 设置 > 模板商店，浏览可用模板并一键安装
2. GitHub 搜索 — 在 GitHub 上搜索带有 presto-template topic 的仓库，找到喜欢的模板后按仓库说明安装
3. ZIP 文件导入 — 打开 设置 > 模板管理 > 从 ZIP 导入，选择下载好的模板 ZIP 文件
4. 拖放 ZIP — 直接把模板 ZIP 文件拖入 Presto 窗口，自动识别并安装
5. 深度链接 — 点击 presto://install/{template-name} 格式的链接（通常在网页上），Presto 会自动打开并安装对应模板

管理已安装的模板

打开 设置 > 模板管理，可以查看所有已安装的模板。在这里你可以卸载不需要的模板或重命名模板。

社区模板

除了官方模板，Presto 还支持社区开发者制作的模板。使用社区模板前，需要在 设置 中开启"社区模板"开关。

安全提示：社区模板由第三方开发者提供，Presto 无法保证其安全性。建议只安装来源可信的模板，留意模板的 信任等级标记。

---

第四部分：进阶功能

批量转换

当你有多个文档需要转换时，不必逐个操作：

1. 把多个 Markdown 文件或一个 ZIP 包拖入 Presto
2. Presto 会自动根据每个文件 frontmatter 中的 template 字段分组
3. 你可以用 Cmd+点击（macOS）或 Ctrl+点击（Windows）多选文件，也可以用 Shift+点击 进行范围选择，还能拖拽调整分组
4. 点击转换后，Presto 会并发处理（3 个 worker 并行），完成后可以单独下载每个 PDF 或打包成 ZIP 一次下载

拖放支持

Presto 支持直接拖放文件到窗口中：

• 支持的文件格式：.md、.markdown、.txt、.zip
• 拖入单个文件 — 在编辑器中打开
• 拖入多个文件 — 进入批量转换模式
• 拖入 ZIP — 自动识别内容：如果是模板则安装，如果包含文档则提取并进入批量转换

自动更新

Presto 支持应用内检查更新：打开 设置 > 关于 > 检查更新。

发现新版本后，三个平台的更新方式：

• macOS — 下载新版 DMG 并自动替换
• Windows — 下载更新包并通过批处理脚本替换
• Linux — 下载新版并覆盖安装

注意：开发版本（dev）不会收到更新提示。

---

第五部分：快捷键速查

快捷键 (macOS / Windows)	功能
Cmd+O / Ctrl+O	打开文件
Cmd+E / Ctrl+E	导出 PDF
Cmd+, / Ctrl+,	打开设置
Cmd+Shift+T / Ctrl+Shift+T	模板管理
Cmd+F / Ctrl+F	编辑器内搜索
Cmd+Z / Ctrl+Z	撤销
Cmd+M / Ctrl+M	最小化窗口

---

第六部分：常见问题 FAQ

安装问题

macOS 提示"无法验证开发者"

• 症状：双击打开 Presto 时弹出安全警告
• 原因：应用使用 ad-hoc 签名，未经 Apple 认证
• 解决：在终端运行 xattr -cr /Applications/Presto.app，或右键点击应用选择"打开"。详见上方 解除 macOS Gatekeeper 拦截

Windows SmartScreen 拦截

• 症状：首次运行时弹出蓝色警告窗口
• 原因：应用没有商业代码签名证书
• 解决：点击"更多信息"，然后点击"仍要运行"

使用问题

图片不显示

• 症状：预览或导出的 PDF 中图片位置是空白
• 原因：图片路径不正确
• 解决：
  • 如果用 Cmd+O 打开 .md 文件，使用相对路径引用图片
  • 如果直接在编辑器中粘贴内容，使用绝对路径引用图片

预览区域空白

• 症状：右侧预览区域什么都不显示
• 原因：未选择模板，或 frontmatter 格式有误
• 解决：
  • 检查顶部是否已选择模板
  • 检查 frontmatter 是否用 --- 正确包裹，且 YAML 语法无误（注意冒号后要有空格）

导出 PDF 失败

• 症状：点击导出后没有生成文件或报错
• 原因：模板未正确安装，或 Markdown 内容有语法问题
• 解决：
  • 在 设置 > 模板管理 中确认模板已安装
  • 检查 Markdown 语法是否正确

模板问题

安装失败，提示"no binary found"

• 症状：安装模板时报错
• 原因：该模板没有提供你当前操作系统/架构的二进制文件
• 解决：联系模板作者，请求添加对应平台的支持

安装失败，提示"SHA256 mismatch"

• 症状：安装模板时校验失败
• 原因：下载的二进制文件与预期的校验值不匹配，可能是文件被篡改或下载不完整
• 解决：重新下载尝试；如果仍然失败，联系模板作者确认

字体缺失警告

• 症状：转换时提示缺少某个字体
• 原因：模板需要特定字体，但你的系统上没有安装
• 解决：桌面端按提示下载并安装到系统字体目录；Docker Web 端把字体文件放入 ./.presto-data/fonts 后重启服务

转换超时

• 症状：转换过程卡住或超时报错
• 原因：文档过长或模板处理逻辑复杂
• 解决：尝试将文档拆分成较短的部分分别转换

大小限制

• 单个 Markdown 文件最大：10 MB
• ZIP 上传最大：100 MB