confluence

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Confluence with orbit CLI

借助orbit CLI管理Confluence

Manage Confluence pages, publish markdown documentation, and control page layout using the

orbit

CLI. Supports Confluence Cloud and Server/Data Center via REST API with multi-profile support and 1Password secret resolution.

使用

orbit

CLI管理Confluence页面、发布Markdown文档并控制页面布局。通过REST API支持Confluence Cloud与Server/Data Center，具备多配置文件支持和1Password密钥解析功能。

Prerequisites

前置条件

```
orbit
```
binary built and accessible

A profile with a

confluence-cloud

confluence-server

service configured in

~/.config/orbit/config.yaml

Valid credentials (API token for Cloud, PAT for Server) — can be stored in 1Password with
```
op://
```
prefix
For Cloud: auth type is
```
basic
```
with email as username and API token as password

已构建并可访问
```
orbit
```
二进制文件

在

~/.config/orbit/config.yaml

中配置了带有

confluence-cloud

或

confluence-server

服务的配置文件

有效的凭据（Cloud使用API令牌，Server使用PAT）——可通过
```
op://
```
前缀存储在1Password中
对于Cloud：认证类型为
```
basic
```
，用户名是邮箱，密码是API令牌

Quick Reference

快速参考

All commands follow the pattern:

orbit -p <profile> confluence <command> [flags]

For full command details and flags, see

references/commands.md

. For Confluence storage format (XHTML) details, see

references/storage-format.md

所有命令遵循以下格式：

orbit -p <profile> confluence <command> [flags]

完整命令详情和参数请查看

references/commands.md

。 Confluence存储格式（XHTML）详情请查看

references/storage-format.md

。

Core Workflows

核心工作流

Viewing Pages

查看页面

bash

undefined

bash

undefined

View page details

查看页面详情

orbit -p myprofile confluence page 473676972036

View as JSON (includes body content)

以JSON格式查看（包含正文内容）

orbit -p myprofile confluence page 473676972036 -o json

List child pages

列出子页面

orbit -p myprofile confluence children 473676972036

undefined

orbit -p myprofile confluence children 473676972036

undefined

Creating Pages from Markdown

从Markdown创建页面

When creating a page from a markdown file, the CLI automatically converts it to Confluence storage format (XHTML). The converter handles headings, lists, tables, code blocks, blockquotes, inline formatting, and images.

bash

undefined

从Markdown文件创建页面时，CLI会自动将其转换为Confluence存储格式（XHTML）。转换器支持标题、列表、表格、代码块、块引用、内联格式和图片。

bash

undefined

Create page from markdown file

从Markdown文件创建页面

orbit -p myprofile confluence create --space FO --parent 473677299713
--title "My New Page" --file docs/overview.md

Create page with inline body (storage format XHTML)

使用内联正文（存储格式为XHTML）创建页面

orbit -p myprofile confluence create --space FO --parent 473677299713
--title "Quick Page" --body "Hello world"


Pages are automatically created with **wide width** (full-width layout).

orbit -p myprofile confluence create --space FO --parent 473677299713
--title "Quick Page" --body "Hello world"


创建的页面会自动设置为**宽屏**（全宽布局）。

Updating Existing Pages

更新现有页面

IMPORTANT — Title updates require
--title
: The

update

command only updates the page body by default. If the frontmatter

title:

has changed, you must pass

--title

explicitly — otherwise the Confluence page title stays unchanged. The

publish

command handles this automatically (reads title from frontmatter), but single-file

update

does not.

bash

undefined

重要提示——更新标题需添加
--title
参数：默认情况下，

update

命令仅更新页面正文。如果前置元数据中的

title:

已更改，必须显式传递

--title

参数——否则Confluence页面标题将保持不变。

publish

命令会自动处理此问题（从前置元数据读取标题），但单文件

update

命令不会。

bash

undefined

Update page content only (title unchanged)

仅更新页面内容（标题不变）

orbit -p myprofile confluence update 473676972036 --file docs/overview.md

Update title AND content — ALWAYS do this when title has changed

更新标题和内容——标题更改时务必执行此操作

orbit -p myprofile confluence update 473676972036
--title "Updated Title" --file docs/overview.md

Update with inline storage format

使用内联存储格式更新

orbit -p myprofile confluence update 473676972036 --body "New content"


**When updating a single page from a markdown file:**
1. Read the frontmatter `title:` field from the file
2. Always pass `--title "<title>"` along with `--file` to ensure the Confluence page title stays in sync
3. This avoids stale titles on Confluence while the body content is updated

orbit -p myprofile confluence update 473676972036 --body "New content"


**从单个Markdown文件更新页面时：**
1. 从文件中读取前置元数据的`title:`字段
2. 务必同时传递`--title "<title>"`和`--file`参数，确保Confluence页面标题保持同步
3. 避免Confluence上的标题过时，而正文内容已更新

Publishing a Directory of Markdown Files

发布Markdown文件目录

The

publish

command recursively converts an entire directory of markdown files to Confluence pages, preserving the folder hierarchy:

```
INDEX.md
```
files become the parent page for their directory
Other
```
.md
```
files become child pages under the directory's parent
Subdirectories are processed recursively
Page titles come from frontmatter
```
title:
```
, first
```
# heading
```
, or filename
Files with
```
confluence_ignore: true
```
are skipped; if previously published, the Confluence page is deleted. When an
```
INDEX.md
```
is ignored, the entire subdirectory is skipped.
Upsert behavior: If a page has no
```
confluence_page_id
```
in frontmatter, orbit searches by title first. If create fails due to a title conflict (e.g. special characters like
```
&
```
in the title), it falls back to listing the parent's children and updating the matching page. After success,
```
confluence_page_id
```
is written to frontmatter for future runs.
All pages are set to full-width layout on every create and update.

bash

undefined

publish

命令会递归将整个Markdown文件目录转换为Confluence页面，并保留文件夹层级：

```
INDEX.md
```
文件成为其所在目录的父页面
其他
```
.md
```
文件成为该目录父页面的子页面
子目录会被递归处理
页面标题来自前置元数据的
```
title:
```
、第一个
```
# 标题
```
或文件名
带有
```
confluence_ignore: true
```
的文件会被跳过；如果之前已发布，对应的Confluence页面会被删除。若
```
INDEX.md
```
被忽略，整个子目录都会被跳过。
更新插入（Upsert）行为：如果页面前置元数据中没有
```
confluence_page_id
```
，orbit会先按标题搜索。如果因标题冲突（例如标题中包含
```
&
```
等特殊字符）导致创建失败，会回退到列出父页面的子页面并更新匹配的页面。操作成功后，
```
confluence_page_id
```
会写入前置元数据，供后续运行使用。
所有页面在创建和更新时都会设置为全宽布局。

bash

undefined

Publish entire docs directory

发布整个docs目录

orbit -p myprofile confluence publish ./docs --space FO --parent 473677299713

Preview what would be created (no API calls)

预览即将创建的内容（不调用API）

orbit -p myprofile confluence publish ./docs --space FO --parent 473677299713 --dry-run

undefined

orbit -p myprofile confluence publish ./docs --space FO --parent 473677299713 --dry-run

undefined

Setting Page Width

设置页面宽度

bash

undefined

bash

undefined

Set single page to wide

将单个页面设置为宽屏

orbit -p myprofile confluence set-width 473676972036

Set page and all children to wide

将页面及其所有子页面设置为宽屏

orbit -p myprofile confluence set-width 473676972036 --recursive

Set to fixed width

设置为固定宽度

orbit -p myprofile confluence set-width 473676972036 --width fixed

undefined

orbit -p myprofile confluence set-width 473676972036 --width fixed

undefined

Markdown Frontmatter Tracking

Markdown前置元数据跟踪

When publishing or converting markdown files for Confluence, track the mapping between local files and Confluence pages using YAML frontmatter. After creating or updating a page, update the source markdown file's frontmatter with:

yaml

---
title: "My Page Title"
confluence_ignore: false
confluence_page_id: "473676972036"
confluence_url: "https://mysite.atlassian.net/wiki/spaces/FO/pages/473676972036/My+Page+Title"
---

This enables:

Re-running updates without needing to look up page IDs
Tracking which files have been published
Building scripts that sync local changes to Confluence
Excluding files from Confluence with
```
confluence_ignore: true
```
(deletes previously published pages)

When the user asks to publish or sync markdown files to Confluence:

Run the orbit command to create/update the page
Capture the page ID and URL from the output
Update the markdown file's frontmatter with
```
confluence_page_id
```
and
```
confluence_url
```
If the frontmatter doesn't exist, add it at the top of the file

Example workflow for syncing a file:

bash

undefined

发布或转换Markdown文件用于Confluence时，可使用YAML前置元数据跟踪本地文件与Confluence页面的映射关系。创建或更新页面后，在源Markdown文件的前置元数据中添加以下内容：

yaml

---
title: "My Page Title"
confluence_ignore: false
confluence_page_id: "473676972036"
confluence_url: "https://mysite.atlassian.net/wiki/spaces/FO/pages/473676972036/My+Page+Title"
---

这实现了：

无需查找页面ID即可重新运行更新
跟踪哪些文件已发布
构建将本地更改同步到Confluence的脚本
通过
```
confluence_ignore: true
```
排除文件（删除之前已发布的页面）

当用户要求将Markdown文件发布或同步到Confluence时：

运行orbit命令创建/更新页面
从输出中捕获页面ID和URL
在Markdown文件的前置元数据中更新
```
confluence_page_id
```
和
```
confluence_url
```
如果前置元数据不存在，在文件顶部添加

同步文件的示例工作流：

bash

undefined

If confluence_page_id exists in frontmatter, update (always include --title):

如果前置元数据中存在confluence_page_id，执行更新（务必包含--title）：

orbit -p myprofile confluence update 473676972036
--title "Overview" --file docs/overview.md

If no confluence_page_id, create new:

如果没有confluence_page_id，创建新页面：

orbit -p myprofile confluence create --space FO --parent 473677299713
--title "Overview" --file docs/overview.md

Then update the frontmatter with the returned page ID and URL

然后在前置元数据中添加返回的页面ID和URL

undefined

undefined

Page Properties & Labels

页面属性与标签

The

publish

command supports Confluence Page Properties macros and labels via frontmatter, enabling dynamic Page Properties Report tables (like the ISMS Policies page pattern).

publish

命令支持通过前置元数据设置Confluence页面属性宏和标签，可生成动态的页面属性报告表格（如ISMS策略页面模式）。

Labels (Tags)

标签（Tags）

Add

confluence_labels

to frontmatter to tag pages. Labels are applied after each page is created or updated during

publish

yaml

---
title: "My Policy"
confluence_labels:
  - ai-process
  - foundation
---

在前置元数据中添加

confluence_labels

可为页面添加标签。标签会在

publish

过程中，页面创建或更新后应用。

yaml

---
title: "My Policy"
confluence_labels:
  - ai-process
  - foundation
---

Page Properties (details macro)

页面属性（详情宏）

Add

confluence_properties

to frontmatter to generate a Confluence Page Properties macro at the top of the page. This creates a structured metadata block that can be queried by Page Properties Report macros on other pages.

yaml

---
title: "Compounding Engineering & System Evolution"
confluence_properties:
  id: status
  fields:
    Owner: AI Tooling Guild
    Classification: Internal
    Status: "{status:Green|approved}"
    Reviewed on: 2026-03-06
    Approved on: 2026-03-06
---

```
id
```
-- sets the macro ID (used by
```
detailssummary
```
reports to target specific property blocks)
```
fields
```
-- ordered key-value pairs rendered as a two-column table inside the macro
Values matching
```
{status:Color|Text}
```
are converted to status badge macros
Values matching
```
YYYY-MM-DD
```
are converted to Confluence
```
<time>
```
date macros
Other values are rendered as plain text

在前置元数据中添加

confluence_properties

可在页面顶部生成Confluence页面属性宏。这会创建一个结构化元数据块，可被其他页面的页面属性报告宏查询。

yaml

---
title: "Compounding Engineering & System Evolution"
confluence_properties:
  id: status
  fields:
    Owner: AI Tooling Guild
    Classification: Internal
    Status: "{status:Green|approved}"
    Reviewed on: 2026-03-06
    Approved on: 2026-03-06
---

```
id
```
-- 设置宏ID（供
```
detailssummary
```
报告用于定位特定属性块）
```
fields
```
-- 有序的键值对，在宏内呈现为两列表格
匹配
```
{status:Color|Text}
```
的值会转换为状态徽章宏
匹配
```
YYYY-MM-DD
```
的值会转换为Confluence
```
<time>
```
日期宏
其他值会呈现为纯文本

Page Properties Report (detailssummary macro)

页面属性报告（详情摘要宏）

Add a directive in your markdown to generate a dynamic table that pulls Page Properties from labeled pages. Two formats are supported:

HTML comment format (full control):

markdown

<!-- confluence:properties-report cql="label = 'ai-process' and space = currentSpace()" firstcolumn="Document" headings="Status, Classification, Reviewed on" -->

Shorthand format:

markdown

{properties-report: label="ai-process", columns="Status, Classification, Reviewed on"}

Parameters:

cql

-- CQL query to find pages (e.g.,

label = "policy" and space = currentSpace()

)

label

-- shorthand for CQL: generates

label = "value" and space = currentSpace()

```
firstcolumn
```
-- name of the first column (defaults to "Title")
```
columns
```
/
```
headings
```
-- comma-separated list of property names to show as columns
```
sortBy
```
-- optional column to sort by

在Markdown中添加指令可生成动态表格，从带标签的页面中提取页面属性。支持两种格式：

HTML注释格式（完全控制）：

markdown

<!-- confluence:properties-report cql="label = 'ai-process' and space = currentSpace()" firstcolumn="Document" headings="Status, Classification, Reviewed on" -->

简写格式：

markdown

{properties-report: label="ai-process", columns="Status, Classification, Reviewed on"}

参数：

cql

-- 用于查找页面的CQL查询（例如

label = "policy" and space = currentSpace()

）

label

-- CQL的简写：生成

label = "value" and space = currentSpace()

```
firstcolumn
```
-- 第一列的名称（默认为“Title”）
```
columns
```
/
```
headings
```
-- 作为列显示的属性名称的逗号分隔列表
```
sortBy
```
-- 可选的排序列

Complete Example

完整示例

Child page (e.g.,
overview.md
):

yaml

---
title: Overview & Philosophy
confluence_labels:
  - ai-process
confluence_properties:
  id: status
  fields:
    Owner: AI Tooling Guild
    Classification: Internal
    Status: "{status:Green|approved}"
    Reviewed on: 2026-03-06
---

Index page (e.g.,
INDEX.md
):

markdown

---
title: AI Development Process
confluence_labels:
  - ai-process
---

子页面（如
overview.md
）：

yaml

---
title: Overview & Philosophy
confluence_labels:
  - ai-process
confluence_properties:
  id: status
  fields:
    Owner: AI Tooling Guild
    Classification: Internal
    Status: "{status:Green|approved}"
    Reviewed on: 2026-03-06
---

索引页面（如
INDEX.md
）：

markdown

---
title: AI Development Process
confluence_labels:
  - ai-process
---

AI Development Process

Document	Version	Summary
Overview & Philosophy	v2.0	Core principles, four layers


On Confluence, only the Properties Report macro is rendered (the static table is ignored). In markdown viewers (GitHub, local), the static table is shown alongside the HTML comment directives (which are invisible).

Document	Version	Summary
Overview & Philosophy	v2.0	Core principles, four layers


在Confluence上，仅会呈现属性报告宏（静态表格会被忽略）。在Markdown查看器（GitHub、本地）中，静态表格会与HTML注释指令（不可见）一同显示。

Markdown-to-Confluence Conversion

Markdown到Confluence的转换

The converter handles the following transformations:

Markdown	Confluence Storage Format
`# Heading` (first one)	Skipped -- Confluence shows the page title
`## Heading` to `###### Heading`	`<h2>` to `<h6>`
`bold`	`<strong>`
`code`	`<code>`
`~~strike~~`	`<del>`
`- bullet` / `* bullet`	`<ul><li>`
`1. numbered`	`<ol><li>`
`> blockquote`	Info panel macro
```lang code blocks	Code macro with language
`\| table \| rows \|`	`<table>` with `<thead>`
`![alt](url)`	`<ac:image>`
`[text](url)`	`<a href>` (relative .md links resolved to Confluence page links)
`---` horizontal rules	`<hr />`
YAML frontmatter	Stripped
`Key: Value` metadata lines	Two-column table (gray label column)
`<!-- confluence:toc-start/end -->`	TOC section replaced with Confluence `toc` macro
`confluence_properties` frontmatter	Page Properties ( `details` ) macro
`<!-- confluence:properties-report -->`	Page Properties Report ( `detailssummary` ) macro
`{properties-report: ...}`	Page Properties Report ( `detailssummary` ) macro
`<!-- confluence:ignore-start/end -->`	Content between markers is skipped (not sent to Confluence)

Key behaviors to communicate to users:

The first
```
# heading
```
is always skipped because Confluence already displays the page title
Relative markdown links (
```
.md
```
,
```
./
```
) are resolved to Confluence internal page links when publishing a directory (using the
```
publish
```
command). The link map maps relative paths to page titles, generating
```
<ac:link>
```
macros. When converting a single file without a link map, relative links fall back to plain text
TOC sections wrapped in
```

```
/
```

```
directives are replaced with Confluence's built-in TOC macro. Supports params:
```
maxLevel
```
,
```
minLevel
```
,
```
style
```
,
```
outline
```
,
```
printable
```
(e.g.,
```

```
). Section numbering (
```
outline
```
) defaults to
```
false
```
to avoid duplicate numbering when the markdown TOC already uses numbered lists
Code blocks and tables use full-width layout
Document metadata lines (
```
**Key**: Value
```
) right after frontmatter are converted to a styled two-column table with gray labels
Code blocks with language hints get syntax highlighting via the code macro
```
confluence_labels
```
in frontmatter applies labels/tags to pages during
```
publish
```
```
confluence_properties
```
in frontmatter generates a Page Properties macro prepended to page content
Properties Report directives generate dynamic tables querying labeled pages
```

```
/
```

```
blocks are stripped during conversion — content inside is completely skipped. This is useful for INDEX pages that need static markdown tables for GitHub/local rendering alongside dynamic Properties Report macros for Confluence. Ignore directives inside code blocks are treated as literal text (not processed)

转换器会处理以下转换：

Markdown	Confluence存储格式
`# Heading` （第一个）	跳过——Confluence会显示页面标题
`## Heading` 至 `###### Heading`	`<h2>` 至 `<h6>`
`bold`	`<strong>`
`code`	`<code>`
`~~strike~~`	`<del>`
`- bullet` / `* bullet`	`<ul><li>`
`1. numbered`	`<ol><li>`
`> blockquote`	信息面板宏
```lang 代码块	带语言的代码宏
`\| table \| rows \|`	带 `<thead>` 的 `<table>`
`![alt](url)`	`<ac:image>`
`[text](url)`	`<a href>` （相对.md链接会解析为Confluence页面链接）
`---` 水平分隔线	`<hr />`
YAML前置元数据	移除
`Key: Value` 元数据行	两列表格（灰色标签列）
`<!-- confluence:toc-start/end -->`	TOC部分替换为Confluence `toc` 宏
`confluence_properties` 前置元数据	页面属性（ `details` ）宏
`<!-- confluence:properties-report -->`	页面属性报告（ `detailssummary` ）宏
`{properties-report: ...}`	页面属性报告（ `detailssummary` ）宏
`<!-- confluence:ignore-start/end -->`	标记之间的内容会被跳过（不会发送到Confluence）

需告知用户的关键行为：

第一个
```
# 标题
```
会被跳过，因为Confluence已显示页面标题
发布目录时（使用
```
publish
```
命令），相对Markdown链接（
```
.md
```
、
```
./
```
）会解析为Confluence内部页面链接。链接映射会将相对路径映射到页面标题，生成
```
<ac:link>
```
宏。当转换单个文件且无链接映射时，相对链接会回退为纯文本
包裹在
```

```
/
```

```
指令中的TOC部分会替换为Confluence内置的TOC宏。支持参数：
```
maxLevel
```
、
```
minLevel
```
、
```
style
```
、
```
outline
```
、
```
printable
```
（例如
```

```
）。章节编号（
```
outline
```
）默认为
```
false
```
，避免Markdown TOC已使用编号列表时出现重复编号
代码块和表格使用全宽布局
前置元数据后的
```
**Key**: Value
```
元数据行转换为带灰色标签列的两列表格
带语言提示的代码块会通过代码宏实现语法高亮
前置元数据中的
```
confluence_labels
```
会在
```
publish
```
过程中为页面添加标签
前置元数据中的
```
confluence_properties
```
会在页面内容前生成页面属性宏
属性报告指令会生成查询带标签页面的动态表格
```

```
/
```

```
块在转换时会被移除——内部内容会完全跳过。这对需要为GitHub/本地渲染显示静态Markdown表格，同时为Confluence显示动态属性报告宏的索引页面非常有用。代码块内的忽略指令会被视为纯文本（不处理）

Important Notes

重要说明

Wide width by default -- All pages created via
```
orbit
```
are automatically set to full-width layout. Use
```
set-width --width fixed
```
to revert.
Cloud vs Server -- Use service type
```
confluence-cloud
```
for Atlassian Cloud (requires
```
/wiki/
```
prefix in API paths, handled automatically). Use
```
confluence-server
```
for Data Center.
Auth for Cloud -- Basic auth with your email as username and an API token (not your password) as the password field.
1Password integration -- Credentials in config can use
```
op://vault/item/field
```
and are resolved at runtime. Run
```
orbit auth
```
once to resolve and cache all secrets for 8 hours (single biometric prompt). Use
```
orbit auth clear
```
to wipe the cache.
Dry run before publish -- Always use
```
--dry-run
```
first when publishing a directory to preview the page hierarchy before making API calls.

默认宽屏——所有通过
```
orbit
```
创建的页面都会自动设置为全宽布局。使用
```
set-width --width fixed
```
可恢复为固定宽度。
Cloud与Server区别——Atlassian Cloud使用
```
confluence-cloud
```
服务类型（API路径需包含
```
/wiki/
```
前缀，会自动处理）。Data Center使用
```
confluence-server
```
。
Cloud认证——基础认证，用户名是你的邮箱，密码是API令牌（而非你的账户密码）。
1Password集成——配置中的凭据可使用
```
op://vault/item/field
```
格式，运行时会解析。运行
```
orbit auth
```
一次即可解析并缓存所有密钥8小时（仅需一次生物识别验证）。使用
```
orbit auth clear
```
可清除缓存。
发布前先试运行——发布目录时务必先使用
```
--dry-run
```
参数，在调用API前预览页面层级。