kb2md 0.3.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

升级

# 直接升级到最新版本
kb2md update

# 仅检查是否有新版本，不执行安装
kb2md update --check

执行其他命令时，kb2md 会在后台自动检查 PyPI 是否有新版本。如果检测到有更新，会在命令结束后提示：

A new version of kb2md is available: 0.3.0 (current 0.2.0). Run `kb2md update` to upgrade.

后台检查默认每 24 小时最多执行一次，结果缓存在 ~/.kb2md/config.json 中。

注意：kb2md update 通过 pip install --upgrade kb2md 升级。如果你是通过 pipx、系统包管理器或只读环境安装的，可能需要使用对应的管理器手动升级。

命令行参数

参数	说明
page_ref	页面 ID、Confluence URL，或 update 升级命令
--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	显示版本
--check	与 update 一起使用时只检查新版本，不安装

输出结构

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

附件下载与 Cookie

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

• macOS：kb2md 通过 pycookiecheat 自动读取 Chrome 中的 Cookie，使用时需满足以下条件：

  1. 使用 Chrome 浏览器。
  2. 浏览器中已登录 Confluence 知识库系统。

  首次下载时会弹出系统提示对话框：

  Python 想要使用您存储在钥匙串的“Chrome Safe Storage”中的机密信息。

  此时需要输入当前电脑用户的登录密码进行确认：

  • 如果选择“允许”，则每次运行 kb2md 时都会再次弹出该对话框。
  • 建议选择“始终允许”，后续使用时便不会再提示。

  

  • 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