Presto 文档

简体中文

English

简体中文

English

主题

用户使用帮助 ​

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

第一部分：安装 ​

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

bash
brew install --cask brewforge/more/presto
bash
# 从 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（一个常用的软件管理工具）， 在终端中运行：

bash
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 中搜索"终端"）， 粘贴以下命令并按回车：

bash
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 SmartScreen 可能会弹出蓝色警告窗口。 这和 macOS 的情况类似——因为应用没有购买商业代码签名证书。 点击"更多信息"，然后点击"仍要运行"即可。

Linux 安装 ​

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

  2. 解压文件：

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

  3. 运行 Presto：

    bash
    ./Presto

Docker 部署（Web 端） ​

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

快速启动：

bash
docker compose up -d

或使用预构建镜像：

bash
docker run -d -p 8080:8080 \
  -v presto-data:/home/presto/.presto \
  ghcr.io/mrered/presto

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

HTTPS 部署：修改 Caddyfile 中的域名为你的实际域名，然后运行：

bash
docker compose -f docker-compose.yml -f docker-compose.tls.yml up -d

安全特性：容器默认以只读文件系统运行、使用非 root 用户、 移除所有 Linux capabilities（cap_drop: ALL）、仅绑定 localhost。

第二部分：基本使用 ​

核心工作流 ​

  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 示例：

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

内置模板 ​

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

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

第三部分：模板管理 ​

安装模板 ​

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" ​

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

字体缺失警告 ​

  • 症状：转换时提示缺少某个字体
  • 原因：模板需要特定字体，但你的系统上没有安装
  • 解决：按照提示信息下载并安装所需字体

转换超时 ​

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

大小限制 ​

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

Presto — Markdown to PDF