从 Quarto 单向发布并维护 Confluence 文档树-未完纪

原文：Quarto 官方指南：Confluence，页面未单独署个人作者。本文根据 2026 年 10 月 05 日完整读取的滚动在线指南编译；没有推定首次发表日期或最低 CLI 版本。以下操作只做静态核对，没有使用真实账户或执行发布。

Quarto 可以把单个文档或由多个文档组成的项目发布到 Confluence Space。这样可以在 Markdown 文件中写作，用 Git 等工具记录变更，并把计算结果纳入文档。前提是团队接受同一个编辑模型：本地 Quarto 文件是内容来源，Confluence 是发布目的地。

适用范围：原指南目前只支持 Confluence Cloud，不支持 Confluence Server 或 Data Center。Confluence 有免费与付费方案，具体权限取决于目的地。向公开空间发布会公开文档内容，不能仅凭“公司账号登录”就认定目标是私有的。

原创示意图：目录结构会形成页面层级，但内容流向始终是从 Quarto 到 Confluence。

先用一个文档走通发布流程

建立 confluence-demo.qmd，原文示例的完整内容如下：

---
title: Confluence Demo
format: confluence-html
---

## Overview

Write your content in Quarto documents and publish to Confluence.

format: confluence-html 让本地预览尽量接近 Confluence 的表现。可以在 RStudio 使用 Render，在 VS Code 或 Positron 使用 Preview 或 Quarto: Preview，也可以运行：

quarto preview confluence-demo.qmd

预览不是发布页面的逐像素承诺。页头中的发布日期、作者和阅读时间等内容只是本地占位展示，真正发布后由 Confluence 生成。确认文档内容后，单页发布命令为：

quarto publish confluence confluence-demo.qmd

首次发布会进入账户设置与目的地选择。编辑补充：预览和渲染可能执行文档中的计算代码；接手陌生 .qmd 或 .ipynb 文件时，先检查计算单元和项目配置，再运行命令。本文中的演示文档只有 Markdown，没有可执行计算单元。

设置账户：域名、邮件和 API 令牌

先登录 Confluence，浏览到打算发布的空间或父页面。Quarto 会依次询问 Confluence Domain、Confluence Account Email、Confluence API Token。域名使用目标页面 URL 的站点部分，例如 https://mydomain.atlassian.net/；邮件应属于该站点使用的账户。

API 令牌由账户持有人在 Atlassian API token 管理页创建，再复制到交互提示中。令牌与个人账户关联，不应放进示例代码、公开仓库、截图或日志。具体令牌要求以 Atlassian 的现行账户文档为准。

Quarto 会保存域名、邮件和令牌，供以后的发布使用。这意味着发布设备也属于凭证保护范围。原指南没有在本页说明凭证存储的加密细节，不能据此承诺“保存后一定安全”。

选目的地：空间顶层或某个父页面

Confluence 页面按父子关系组织。提示 Space or Parent Page URL 要求填入父位置的 URL，而不是猜测一个新页面的地址。要让页面出现在空间顶层，填空间 URL；要放在既有页面下面，填父页面 URL：

https://domain.atlassian.net/wiki/spaces/ABBR
https://domain.atlassian.net/wiki/spaces/ABBR/pages/123456

选择目的地后，Quarto 会渲染内容、发送到 Confluence，再打开浏览器查看结果。发布前应同时核对站点域名、空间标识、父页面和可见范围；名字相似的空间并不意味着权限相同。

发布一组文档：目录如何变成页面树

把文档组织为 Quarto 项目，在项目根目录的 _quarto.yml 中指定类型：

project:
  type: confluence

随后按希望发布的层级排列 .qmd 或 .ipynb 文档，例如：

_quarto.yml
index.qmd
team.qmd
projects/
  planning.qmd
  retrospectives.qmd

也可以用模板建立新项目：

quarto create project confluence

在项目目录运行 quarto preview 可以预览整个项目。预览会生成一个带侧边导航的 HTML 网站，方便本地浏览；发布后的导航由 Confluence 自身管理。要发布整个项目，在项目目录运行：

quarto publish confluence

账户与目的地的选择过程与单页相同。Quarto 会先创建一个承载整个项目的页面：项目根目录的文档成为其子页面；子文件夹也用页面表示，文件夹内的文档继续作为该页面的子页面。原文以如下目录解释这层映射：

example-project/
├── _quarto.yml
├── project-roadmap.qmd
├── reports-folder/
│   ├── 2023-01.qmd
│   └── 2023-03.qmd
└── team-members.qmd

侧栏标题来自文档 YAML 的标题、_quarto.yml 的项目标题，或文件夹名称。Confluence 要求同一空间中的页面名称唯一，因此 Quarto 可能在标题上添加额外字符；不能把显示名原样不变当成外部程序的稳定约定。

用 index.qmd 填充文件夹页面

表示文件夹的页面默认没有正文。若文件夹内有 index.qmd，该文件会填充文件夹页面。比如在 reports-folder 中增加：

---
title: Reports
---

Monthly reports on project progress

重新发布后，原来表示 reports-folder 的页面标题会变为 Reports，并显示这一段内容。这个索引文件适合写目录说明、阅读顺序或月报的背景，不需要再额外维护一个网页端介绍页。

更新是单向的，发布账户也要稳定

由 Quarto 管理的页面，修改应发生在本地项目中，然后再次执行发布命令。Confluence 网页端的正文修改不会回传，下一次发布会将其覆盖。行内评论同样会被覆盖；页面级评论和页面级表情可以跨发布保留。

为减少他人误改，Quarto 会尝试把页面权限设为：有权访问空间的人可以查看，只有发布者可以编辑。编辑权限也包含更新发布，因此后续更新应由最初发布的同一账户完成。

如果发布者没有控制页面权限的能力，Quarto 会尝试检测并告警。继续发布后，所有有空间访问权的人可能都能查看和编辑这些页面。这个告警代表协作方式与覆盖风险已经变化，不能把默认权限限制当成无条件保证。

页面被删后，为什么重新发布得到 404

Quarto 会在 _publish.yml 保存并复用远端页面位置。如果页面在 Confluence 被删除，旧位置便失效，重新发布可能得到：

ERROR: API Error: 404 - Not Found

原指南的处理方式是删除 _publish.yml 中对应的发布条目，再发布并重新选目的地。编辑补充：应先确认远端确实被删除、账号和权限正常，并只移除那一条记录。把整个发布文件清空，可能让其他文档也失去已有目标关联。

写作支持与明确限制

confluence-html 支持大部分标准 Quarto Markdown 内容，包括表格、提示块和交叉引用。原指南列出的未支持内容有文献引用、视频、图解、标签页组和公式。普通 Quarto 网页可以显示的内容，并不都能无损发布到 Confluence。

Confluence 项目属于特殊的网站类型，传统 Quarto 网站的 Listings、Themes 和 Navigation 由 Confluence 自身机制取代。迁移既有网站时，应逐页预览这些功能，不能只看发布命令成功就认定迁移完整。

项目内链接可以直接指向源文件，也可以附带章节锚点：

[about](about.qmd)
[about](about.qmd#section)

需要 Confluence 专有内容时使用原始块

原始 Confluence 块会原样穿过 Quarto，再由 Confluence 解释。例如任务列表可以使用其 Storage Format 标签。以下是原指南的结构，作为代码显示，不会在本文中执行或渲染成外部组件：

```{=confluence}
<ac:task-list>
    <ac:task>
        <ac:task-status>incomplete</ac:task-status>
        <ac:task-body>task list item</ac:task-body>
    </ac:task>
</ac:task-list>
```

编辑补充：原样透传是一条信任边界。不要把不受信任的输入直接拼进原始块；任务正文或属性值应按目标格式处理。这里的静态示例没有脚本，但不能由此推论任意原始块都安全。

区分发布位置与账户凭证

每次 quarto publish 会自动创建或更新文档/项目目录里的 _publish.yml，记录服务、目标 id 和 URL。原文示例为：

- source: project
  confluence:
    - id: "5f3abafe-68f9-4c1d-835b-9d668b892001"
      url: "https://myteam.atlassian.net/wiki/spaces/TEAMSPACE/pages/123456/Plan"

这些值是原文演示值，不可直接用于自己的项目。后续发布会复用记录；若按原指南手工指定已有目标，必须使用正确的 id 与 URL。该文件不保存账户凭证，可以纳入版本控制，但内部站点地址、空间名和页面标识仍可能包含组织信息，提交前应检查。

发布设置可以共享，并不代表另一个账户自动获得页面更新权限。账户层面的保存信息由以下命令管理：