# MDclient 專案概述

## 什麼是 MDclient？

MDclient 是一個 **Python 函式庫**，用於與 Markdown 筆記服務（如 CodiMD、HedgeDoc、HackMD）互動。

## 核心特色

- **Python 函式庫優先**：主要設計為在 Python 程式碼中使用
- **簡單的 API**：清晰直觀的介面
- **多服務支援**：CodiMD、HedgeDoc、HackMD 等
- **會話管理**：自動儲存和載入 Cookie
- **.env 支援**：方便的設定管理

## 專案結構

```
mdclient/
├── mdclient/           # 核心 Python 函式庫
│   ├── __init__.py    # 匯出 MDClient, MDAuth
│   ├── auth.py        # 認證功能
│   └── client.py      # API 客戶端
├── mdclient_cli.py    # 可選的 CLI 工具
├── example.py         # Python 使用範例
├── auth_example.py    # 認證範例
├── .env.example       # 環境變數範例
├── API.md             # API 文件
├── QUICKSTART.md      # 快速開始
├── README.md          # 完整文件
└── SUMMARY.md         # 本檔案
```

## 使用方式

### 作為 Python 函式庫（主要）

```python
from mdclient import MDClient, MDAuth

# 登入
auth = MDAuth()
auth.login("email@example.com", "password")

# 使用客戶端
client = MDClient()
notes = client.list_notes()
```

### 作為 CLI 工具（可選）

```bash
python3 mdclient_cli.py list
python3 mdclient_cli.py create "標題"
```

## 主要 API

### MDAuth

```python
from mdclient import MDAuth

auth = MDAuth(base_url="...", cookie_file="key.conf")
auth.login(email, password)
auth.test_cookie()
```

### MDClient

```python
from mdclient import MDClient

client = MDClient(base_url="...", cookie_file="key.conf")
client.list_notes()
client.get_note(note_id)
client.create_note(title, content)
client.delete_note(note_id)
client.export_note(note_id, format)
```

## 適用場景

1. **自動化腳本**：定期備份筆記
2. **Web 應用**：整合筆記功能
3. **資料處理**：批次處理筆記
4. **整合工具**：作為其他工具的依賴

## 安裝

```bash
pip install mdclient
```

## 文件

- [README.md](README.md) - 完整文件和安裝指南
- [API.md](API.md) - 詳細的 API 參考
- [QUICKSTART.md](QUICKSTART.md) - 快速開始指南
- [example.py](example.py) - Python 使用範例
- [auth_example.py](auth_example.py) - 認證功能範例

## 設定

支援透過 `.env` 檔案設定：

```env
MDCLIENT_URL=https://codimd.lotimmy.com
MDCLIENT_EMAIL=your@email.com
MDCLIENT_PASSWORD=your_password
```

## 總結

MDclient 是一個專注於 Python 程式碼中使用的 Markdown 筆記服務客戶端函式庫。如果你需要在 Python 專案中操作 CodiMD、HedgeDoc 等服務，這個函式庫就是為你設計的。