Metadata-Version: 2.4
Name: kb2md
Version: 0.3.0
Summary: Convert Confluence pages to Markdown with attachments.
Project-URL: Homepage, https://github.com/slash-xin/kb2md
Project-URL: Repository, https://github.com/slash-xin/kb2md
Author-email: xinyan <slash.xin@gmail.com>
License: MIT
License-File: LICENSE
Keywords: confluence,export,kb,markdown
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: atlassian-python-api>=3.41.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: markdownify>=0.13.0
Requires-Dist: packaging>=22.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: pycookiecheat>=0.8.0
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: bandit>=1.7.0; extra == 'dev'
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.5.0; extra == 'dev'
Description-Content-Type: text/markdown

# kb2md

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

## 安装

```bash
pip install kb2md
```

## 快速开始

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

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

也可以同时设置：

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

### 2. 导出单个页面

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

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

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

### 3. 导出子页面

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

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

## 升级

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

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

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

```text
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` 一起使用时只检查新版本，不安装 |

## 输出结构

```text
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` 时都会再次弹出该对话框。
  - 建议选择“**始终允许**”，后续使用时便不会再提示。

  ![macOS 钥匙串授权对话框](resource/image_20260710191357.png)

  - `pycookiecheat` 项目地址：https://github.com/n8henrie/pycookiecheat
- **Windows**：`pycookiecheat` 不支持 Windows，因此必须手动提供 Cookie：
  1. 在浏览器中登录 Confluence。
  2. 复制当前站点的 Cookie（可通过浏览器开发者工具，或安装 [Cookie Tool](https://chromewebstore.google.com/detail/cookie-tool/gfmallmkikahpafdljpnolhgbhgkheja) 扩展快速复制）。
  3. 执行命令时通过 `--cookie` 传入：
     ```bash
     kb2md 514437503 --cookie "key1=value1; key2=value2"
     ```
  4. 如果未提供 `--cookie`，命令会输出警告，附件将无法下载。

## 环境变量

- `CONFLUENCE_URL`: 默认 Confluence URL
- `CONFLUENCE_TOKEN`: 默认 Token

## 开发

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

## 安全提示

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