Quarto Book Publisher

在 Obsidian 内用图形化工作台把当前 Markdown 文稿排版为出版级 PDF。

插件以 Quarto + Typst 为排版引擎：你可以在导出前预览真实页面，自定义纸张、页边距、章节分页、目录、封面、图片、颜色、字体、页眉与页脚，而不需要手写 Typst 模板。插件不会修改原 Markdown，也不会内置某一本书的专用版式。

当前版本：0.6.4

主要功能

• 图形化出版工作台：左侧调整参数，右侧预览最终排版引擎渲染出的真实页面。
• 封面、目录、正文均可按物理页码预览，并支持缩放。
• 支持 A4、A5、ISO B5、US Letter，以及装订侧、外侧、顶部、底部页边距。
• 章节可连续排版、另起一页，或始终从右手奇数页开始。
• 目录可开关、改名并设置收录层级。
• 奇数页与偶数页的页眉、页码可分别设置左对齐、居中或右对齐。
• 章节标题、小标题、正文、引用块、代码块均可独立设置中文字体与拉丁字体。
• 从 quarto typst fonts 读取最终渲染器真正可用的本机字体；常见中文字体显示中文名称并用自身字形预览。
• 每篇 Markdown 保存自己的上次成功导出配置；再次导出时直接在原配置上修改。
• 支持 Obsidian Wiki 链接、图片嵌入、常用 callout，以及 April's Automatic Timelines 的 aat-vertical 静态展开。
• 输出前显示实时构建日志；只有 Quarto 成功退出且 PDF 基础校验通过后，才复制最终文件。

环境要求

• Obsidian 桌面版 1.8.7 或更高版本。
• Quarto 1.10 或更高版本。
• 已在 Windows 11 上验证。其他桌面系统可能可用，但当前版本尚未完整测试。

Quarto 自带本流程使用的 Pandoc 与 Typst。插件不会联网下载、安装或更新外部程序。

安装

从 Release 安装

1. 在 GitHub Releases 下载 quarto-book-publisher-0.6.4.zip。

2. 解压后，把整个 quarto-book-publisher 文件夹放入：

   <你的 Vault>/.obsidian/plugins/quarto-book-publisher/
   

3. 确认插件目录直接包含以下内容：

   main.js
   manifest.json
   styles.css
   templates/
   

4. 重启 Obsidian，或重新加载应用。

5. 打开“设置 → 第三方插件”，启用 Quarto Book Publisher。

不要只下载 main.js：当前版本在运行时还需要 templates/ 中的 Typst 模板。完整 Release 压缩包已经包含全部文件。

配置 Quarto

如果 quarto 已加入系统 PATH，默认值无需修改。否则，在“设置 → Quarto Book Publisher”中填写 quarto.exe 的绝对路径，例如：

C:\Program Files\Quarto\bin\quarto.exe

然后运行命令“Quarto Book Publisher: 检查出版环境”。

使用方法

1. 在 Obsidian 中打开要出版的 Markdown 文件。
2. 点击左侧功能区的书本图标，或运行命令“Quarto Book Publisher: 打开出版控制台”。
3. 在左侧设置内容范围、封面、页面、字体、图片、页眉页脚及输出位置。
4. 在右侧选择“封面”“目录”或“正文”，输入页码，点击“生成预览”。
5. 确认页面后点击“导出 PDF”。

预览与最终 PDF 使用同一份临时书稿和 Typst 模板，因此预览反映的是实际导出结果，而不是浏览器 CSS 的近似效果。

排版设置

内容与章节

• 整篇文档：移除 YAML frontmatter，保留文稿原有标题层级。
• 从指定标题开始：从精确匹配的二级标题开始，将后续同级标题作为章节。
• 章节起页：连续、每章另起一页、每章从奇数页开始。
• 目录：可设置标题及 1–3 级深度。

如果某篇文稿保存的“正文起始标题”已不存在，插件会安全回退到整篇文档模式，并清除该文稿遗留的封面与页眉信息。

字体

每类文字都可分别指定中文字体与拉丁字体：

• 章节标题
• 小标题
• 正文
• 引用块
• 代码块

拉丁字体留空时，会继承同一类别的中文字体。新配置的默认组合为：

文字类型	中文字体	拉丁字体
章节标题	Noto Sans SC（思源黑体）	继承中文字体
小标题	Noto Sans SC（思源黑体）	继承中文字体
正文	Noto Serif SC（思源宋体）	继承中文字体
引用块	KaiTi（楷体）	继承中文字体
代码块	Microsoft YaHei（微软雅黑）	Consolas

字体列表来自 Typst，而不是浏览器。若某字体没有出现，请先确认 quarto typst fonts 能列出它。

页眉与页脚

• 奇数页和偶数页可使用不同的页眉文字。
• 奇数页、偶数页的页眉与页码各自拥有独立的左/中/右对齐选项。
• 页眉、页码字号可分别调整。
• 封面上的短标签与正文页眉互不绑定。

图片与封面

• 支持 PNG、JPEG、GIF、SVG、WebP 与 PDF 图片。
• 支持 ![[image.png]] 和标准 Markdown 图片语法。
• 图片后的独立斜体段落会作为图注。
• 正文图片以独立图块排版，宽度可统一调整。
• 封面图片可使用 Vault 相对路径或绝对路径。
• 如果 PNG、JPEG、GIF、WebP 或 PDF 的内容与文件扩展名不一致，插件只在临时任务中修正副本名称，不改动 Vault 原文件。

Obsidian 语法兼容

当前支持：

• 有别名与无别名 Wiki 链接，例如 [[条目]]、[[条目|显示文字]] 与 [[条目#章节]]。
• Obsidian 图片嵌入。
• abstract、note、info、warning、quote、tip callout。
• 标题、列表、引用、围栏代码块与分隔线的块级间距规范化。
• aat-vertical 时间线块。

对于 April's Automatic Timelines，插件会读取 Vault 中启用了 aat-render-enabled 的事件笔记，按时间线标签筛选并按 aat-event-start-date 排序，然后把交互式卡片展开为适合纸面阅读的静态事件条目。源时间线和事件笔记不会被修改。

配置保存与文件访问

• 全局默认值和每篇文稿的最近一次成功导出配置保存在插件自己的 data.json 中。
• 文稿配置以 Vault 内 Markdown 路径为键；移动或重命名文稿后会被视为新文稿。
• 默认临时目录为操作系统临时目录下的 quarto-book-publisher，也可改为任意绝对路径。
• 默认输出目录为 Vault 根目录下的 出版输出，也可使用绝对路径。
• 插件不收集遥测，不主动联网，也不上传文稿。

插件需要读取当前 Markdown、引用图片及时间线事件，并在临时目录运行 Quarto。生成成功后，最终 PDF 才会复制到输出目录。

常见问题

“无法启动 quarto”或环境检查失败

在终端执行：

quarto --version
quarto typst fonts

如果系统找不到命令，请在插件设置中填写 quarto.exe 的绝对路径。

字体列表中没有某个字体

插件只显示 Typst 可见的字体。安装字体后重启 Obsidian，再点击“刷新字体列表”。也可直接在字体输入框中填写 Typst 使用的字体族名称。

更新后界面仍是旧版本

确认 manifest.json 中的版本号已经更新，然后重新加载 Obsidian。手动安装时应整体替换插件文件夹，尤其不要遗漏 templates/。

YAMLException 指向正文中的 ---

0.6.2 及以上版本会在临时书稿中安全转换正文分隔线，同时保留代码块里的原文。若仍出现该错误，请确认插件目录没有混用旧版 main.js 与新版 manifest.json。

图片无法解码

0.6.3 及以上版本会识别常见图片的真实格式。若仍失败，请检查图片是否损坏，或是否使用了当前不支持的格式。

已知限制

• 仅处理当前打开的一份合并 Markdown；尚不支持自动合并多个章节文件。
• 不展开 Obsidian 的笔记嵌入，遇到嵌入笔记时会报错。
• Vault 中存在多个同名图片且无法唯一解析时会拒绝构建。
• PDF 校验限于构建状态、文件大小和文件签名，不替代人工校对。
• 当前提供一套完全参数化的通用 Typst 模板，尚不支持多个命名模板方案。
• 真实预览会重新生成临时书稿；图片较多时不会即时完成。

从源码构建

需要 Node.js 20 或更高版本。

npm install
npm test
npm run build

生产构建会生成根目录下的 main.js。发布包还必须包含 manifest.json、styles.css 和整个 templates/ 目录。

项目结构：

src/                    插件 TypeScript 源码
templates/publication/  参数化 Typst 模板
tests/                  Markdown 转换与配置迁移测试
main.js                 生产构建产物
manifest.json           Obsidian 插件清单
styles.css              出版工作台样式

版本记录

详见 CHANGELOG.md。

许可证

MIT License © 2026 七月流火