用 Quarto 打包带计算笔记本的研究稿件-未完纪

一篇计算研究稿件不只有正文。数据清理、分析过程和用于生成图表的笔记本，往往也是读者复核结论所需的材料。Quarto 的 manuscript 项目把这些部分放到同一个出版流程中：文章可以直接来自计算笔记本，笔记本本身也能成为发布记录的一部分，并随标准化稿件包一起交付。

本文依据 Quarto 官方指南 Using Manuscripts 完整整理，重点是本地项目结构、笔记本与资源组织、MECA 交换包和链接配置。外部托管、Binder、评论服务与期刊模板属于可选扩展，使用它们前需要各自的环境和审查。原页未署个人作者；维护与发布方为 Quarto／Posit。本文没有运行 Quarto、执行笔记本或发布任何稿件。

稿件、笔记本与交付物之间的关系。未完纪依据 Quarto 文档绘制；为技术示意图，不是构建结果截图。

从一个 manuscript 项目开始

将 _quarto.yml 中的项目类型设为 manuscript，即可声明这是稿件项目：

project:
  type: manuscript

默认正文可以写在 index.qmd 中，也可以写在 Jupyter 笔记本 index.ipynb 中。如果正文使用别的文件名，在 manuscript 下指定 article：

manuscript:
  article: earthquakes.qmd

希望从模板内容起步时，官方提供以下创建命令：

quarto create project manuscript

后续选项大多写在同一个 _quarto.yml 中。本文各小节的短配置是对不同选项的说明，组合时应合并到同一个 manuscript: 或 format: 映射下，不要重复粘贴多个同名顶层键。文末给出一个合并后的本地示例。

把笔记本放进可追溯的发布记录

项目目录中包含的 .qmd 和 .ipynb 笔记本会成为稿件的一部分。Quarto 会将它们渲染为 HTML 笔记本视图，并在稿件网页的 “Notebooks” 区域链接出来。这让正文中的结论能与计算过程并列呈现，也意味着不应把项目目录当成存放私人草稿的保险箱。

默认链接文字按以下顺序确定：先使用笔记本 YAML 元数据中的 title；如果没有，则用笔记本中的第一个 Markdown 标题；两者都没有时，使用文件名。也可以在项目配置中明确指定：

manuscript:
  notebooks:
    - notebook: notebooks/data-screening.ipynb
      title: Data Processing

notebook 是笔记本路径，title 是给读者看的链接文字。文件名适合稳定地定位材料，展示标题则可以写得更易读；例如这里可以把标题改为“数据筛选过程”，不会改变实际路径。

链接到别处的笔记本

若笔记本托管在其他位置，可以给条目设置 url。原文用 Binder 上的 JupyterLab 示例来说明：一个条目可以保留本地 notebook 路径及标题，但让读者访问外部笔记本页面。此选项提供链接，并不证明外部服务中已经安装了研究所需的依赖。

编辑提示：原页的示例 Binder URL 使用 http:// 并指向可变的 master 分支。实际共享研究环境时应使用提供方支持的 HTTPS 地址，并固定可复核的修订版本；本文不把那个演示仓库当作自己的研究环境，也没有打开其会话或执行代码。

网页展示与下载文件可以分开指定

另一种情况是：希望网页由一份笔记本生成，但读者下载时取得经过专门整理的版本。这时使用 download-url：

manuscript:
  notebooks:
    - notebook: notebooks/data-screening.ipynb
      title: Data Processing
      download-url: notebooks/data-screening-raw.ipynb

这并不会把下载文件自动变成“更安全的原始文件”。两份笔记本都要检查代码、输出单元、嵌入式图片和元数据，确认不会泄露个人数据、访问令牌或本机目录信息。下载目标还必须真实存在，并且在最终发布位置能够访问。

用 Code Links 补齐脚本和仓库入口

code-links 会在稿件网页的 “Code Links” 区域添加链接。以数据导入脚本为例：

manuscript:
  code-links:
    - text: Data Import Code
      icon: file-code
      href: data-import.py

每个条目可以设置 text（显示文字）、href（链接目标）、icon（Bootstrap 图标名称）、rel（HTML 链接关系）和 target（链接打开目标）。这些是链接的表现与目的地选项，不负责审查被链接文件的内容。

原文还定义了两个特殊值。code-links: repo 会生成 GitHub 仓库链接；它需要项目本身是 Git 仓库，并以 GitHub 仓库作为 origin，Quarto 才能据此推断地址。code-links: binder 则用于已经配置 Binder 的项目，显示启动 Binder 的入口。只有打算公开相应仓库或外部计算入口时才启用它们。

# 两种独立示例；根据项目实际条件选用
manuscript:
  code-links: repo

若选择 Binder，对应值为 binder。Binder 的用途是让读者在云环境中恢复计算环境、交互操作笔记本；具体依赖文件和环境配置仍需遵循官方 Using Binder With Quarto 指南。本文的本地打包流程不依赖 Binder。

显式资源会被带到发布输出中

Quarto 会尝试收集将笔记本渲染为 HTML 所需的资源。如果还希望公开某个数据文件，应该在 resources 中明确列出：

manuscript:
  resources:
    - data/earthquakes.csv

这样读者就能通过稿件站点下的 data/earthquakes.csv 路径取得数据，即 {manuscript-url}/data/earthquakes.csv。这是公开资源路径，不是私有附件空间。配置前应确认文件的授权范围、脱敏要求和内容边界；不要为了“避免漏文件”就把包含秘密、个人目录或未审查数据的整个文件夹加入资源列表。

编辑补充：除了源数据，计算笔记本的输出也可能含敏感内容。删除代码中的密钥并不能自动清除已经保存到输出单元的值；发布前应检查实际生成的 HTML、可下载笔记本和压缩包中的文件，而不是只看源配置。

用 MECA 交换整份稿件

MECA 是 Manuscript Exchange Common Approach 的缩写，它定义了一种交换稿件及其资源的标准化包，其中可以包含计算笔记本。Quarto manuscript 项目有两条启用路径：

format:
  html: default
  jats: default

当文章输出格式包括 jats 时，Quarto 会生成 MECA 包。也可以不依赖这个隐式触发，而在稿件配置中明确启用：

manuscript:
  meca-bundle: true

默认包名由文章文件名确定，例如 index-meca.zip。需要稳定交付文件名时，可把 meca-bundle 直接设为名称：

manuscript:
  meca-bundle: "bundle.zip"

这里的“交换包”不是运行复现已经通过的证明。它方便统一交付，实际是否包含读者需要的输入、依赖说明、笔记本及正确链接，仍应检查构建产物。本文没有生成或验证研究项目的 MECA 包，不声称已经完成任何投稿。

让非 HTML 文件里的链接也能找到笔记本

文章的非 HTML 输出需要用稿件网站地址来构造笔记本链接。若项目发布到 GitHub Pages，Quarto 可以自动检测并设置该地址；如果使用其他主机，或者自动检测失败，就应显式设置 manuscript-url。

原文示例值是 www.posit.co。下文的合并示例改用明确带协议的示例域名，以强调它必须被替换为稿件最终部署地址。配置一个地址本身不会发布网站，也不会使本地资源自动出现在那个地址。

一个只依赖本地材料的合并配置

下面的目录和 YAML 是编辑依据原文各选项合并的示例，不是原页逐字提供的完整工程。目录中的数据和笔记本需要作者实际准备、检查并放入相应位置；本文没有虚构这些研究内容或测试它们。

research-manuscript/
├── _quarto.yml
├── index.qmd
├── notebooks/
│   └── data-screening.ipynb
├── data/
│   └── earthquakes.csv
└── data-import.py

project:
  type: manuscript

manuscript:
  article: index.qmd
  notebooks:
    - notebook: notebooks/data-screening.ipynb
      title: 数据筛选过程
  code-links:
    - text: 数据导入脚本
      icon: file-code
      href: data-import.py
  resources:
    - data/earthquakes.csv
  meca-bundle: "bundle.zip"
  manuscript-url: "https://example.org/research/"

format:
  html: default
  jats: default

example.org 是示例域名，须替换为真实发布位置。这里同时列出 JATS 与明确的包名，是为了展示输出和命名的配置位置；并不要求为了生成包而重复开启两套不同的打包过程。正文仍保存在 index.qmd，不把另一个计算笔记本误当作文章入口。

页面样式与外部服务属于后续选择

稿件网页和笔记本视图都属于 HTML 页面，因此可以使用 format.html 的选项。原文以主题 solar 为例：

format:
  html:
    theme: solar

评论功能也在 HTML 格式下配置。原文示例为 comments: { hypothesis: true }，即启用 Hypothes.is；另外还支持 Utterances 和 Giscus。评论功能会引入第三方服务，只有确实需要并接受相应数据交互时再配置，不能把它视为打包本地稿件的前置要求。

若期刊要求专用格式，可从 Quarto 的 Journal Articles 扩展列表选择模板。原文用 quarto-journals/acs 举例：先安装对应扩展，再在 format 中加入 acs-pdf: default，也可以同时保留 html、docx 和 jats。扩展格式名由扩展名与目标格式组合，例如 acs 加 -pdf。

安装扩展会引入外部仓库中的模板、过滤器或其他构建内容，需核对来源、版本和许可证；期刊格式本身也可能有额外工具依赖。本文只解释原文的这条可选路径，没有安装 ACS 或其他扩展，当前核心示例仍以 Quarto 内置格式为限。

交付前核对的是实际输出

静态审查中，本文展示的 YAML 没有硬编码秘密或把外部字符串拼成执行命令。但笔记本渲染可能执行其中的代码，第三方扩展也可能参与构建，因此文件可信程度与执行环境仍然重要。未经检查的笔记本不能仅因扩展名是 .ipynb 就当作被动文档运行。

一份可复核的稿件应当让读者顺着正文找到正确的笔记本，按链接拿到经过审查的数据，并在 MECA 包中找到对应材料。审查时逐一对照显示标题、下载目标、资源路径和非 HTML 链接，记录实际构建结果；本文提供了组织方式与风险边界，本次没有执行构建，不能把它当作 Quarto 版本兼容或产物可用性的测试报告。

文章版权归作者所有，未经允许请勿转载。

THE END