kb2md 0.2.0

Convert Confluence pages to Markdown with attachments.

kb2md

将 Confluence 页面导出为本地 Markdown 文件，并自动下载附件与图片，支持子页面批量导出。

安装

pip install kb2md

快速开始

1. 配置默认 URL 和 Token（可选，推荐）

kb2md --set-default-url https://kb.cvte.com
kb2md --set-default-token "你的PAT"

也可以同时设置：

kb2md --set-default-url https://kb.cvte.com --set-default-token "你的PAT"

2. 导出单个页面

# 使用 page ID（已设置默认 URL 和 Token 时）
kb2md 514437503

# 或使用完整 URL
kb2md https://kb.cvte.com/pages/viewpage.action?pageId=514437503

# 临时指定 Token
kb2md 514437503 --token "你的Token"

3. 导出子页面

# 只导出直接子页面
kb2md --subpage 514437503

# 递归导出所有子页面
kb2md --all-subpage 514437503

命令行参数

参数	说明
page_ref	页面 ID 或 Confluence URL
--url	Confluence base URL（临时覆盖默认值）
--token	Confluence Personal Access Token
--output-dir	输出目录，默认 ./output
--subpage	下载直接子页面
--all-subpage	递归下载所有子页面
--no-chrome-cookies	禁用 Chrome Cookie 下载附件
--cookie	手动指定浏览器 Cookie 下载附件（Windows 必需）
--set-default-url	设置默认 Confluence URL
--set-default-token	设置默认 Confluence Token/PAT
--get-default-url	查看当前默认 URL
--verbose	开启详细日志
--version	显示版本

输出结构

output/
├── 页面标题[514437503].md
└── 514437503_page/
    ├── 子页面标题[childId].md
    ├── childId_attach/
    │   └── ...
    └── childId_page/
        └── ...

附件下载与 Cookie

Confluence 的附件下载接口无法通过 PAT/Token 直接下载，需要借助浏览器中已登录会话的 Cookie。

• macOS：kb2md 通过 pycookiecheat 自动读取 Chrome 中的 Cookie（每次运行会弹出系统授权对话框；可选择“始终允许”避免重复提示）。
  • pycookiecheat 项目地址：https://github.com/n8henrie/pycookiecheat
• Windows：pycookiecheat 不支持 Windows，因此必须手动提供 Cookie：
  1. 在浏览器中登录 Confluence。
  2. 复制当前站点的 Cookie（可通过浏览器开发者工具，或安装 Cookie Tool 扩展快速复制）。
  3. 执行命令时通过 --cookie 传入：

     kb2md 514437503 --cookie "key1=value1; key2=value2"
     

  4. 如果未提供 --cookie，命令会输出警告，附件将无法下载。

环境变量

• CONFLUENCE_URL: 默认 Confluence URL
• CONFLUENCE_TOKEN: 默认 Token

开发

pip install -e ".[dev]"
pytest --cov=kb2md --cov-report=term-missing

安全提示

• 不要把 Token 写死在代码或命令历史中
• 推荐通过环境变量注入 Token
• 使用 --set-default-token 时，Token 会保存在 ~/.kb2md/config.json，该文件权限设置为仅所有者可读写（0o600）
• 共享机器上请谨慎使用 --set-default-token