Timmy
38b4bc5377
- Add MDAuth class for authentication and session management - Add MDClient class for note operations (CRUD + export/search) - Add CLI tool mdclient_cli.py for quick operations - Support for CodiMD, HedgeDoc, and HackMD services - Multi-endpoint API compatibility Co-Authored-By: Claude Sonnet 4 <noreply@anthropic.com>
188 lines
3.1 KiB
Markdown
188 lines
3.1 KiB
Markdown
# MDclient 快速開始
|
|
|
|
## 安裝
|
|
|
|
```bash
|
|
pip install mdclient
|
|
```
|
|
|
|
如果需要 .env 支援：
|
|
|
|
```bash
|
|
pip install "mdclient[env]"
|
|
```
|
|
|
|
## 5 分鐘快速上手
|
|
|
|
### 1. 匯入函式庫
|
|
|
|
```python
|
|
from mdclient import MDClient, MDAuth
|
|
```
|
|
|
|
### 2. 登入
|
|
|
|
```python
|
|
auth = MDAuth()
|
|
auth.login("your@email.com", "password")
|
|
```
|
|
|
|
### 3. 使用客戶端
|
|
|
|
```python
|
|
# 列出筆記
|
|
client = MDClient()
|
|
notes = client.list_notes()
|
|
|
|
for note in notes:
|
|
print(f"{note['text']} - {note['id']}")
|
|
```
|
|
|
|
## 常用操作
|
|
|
|
### 建立筆記
|
|
|
|
```python
|
|
client = MDClient()
|
|
result = client.create_note("我的筆記", "# 內容\n\n這是筆記內容")
|
|
```
|
|
|
|
### 取得筆記
|
|
|
|
```python
|
|
note = client.get_note(note_id)
|
|
print(note['content'])
|
|
```
|
|
|
|
### 匯出筆記
|
|
|
|
```python
|
|
content = client.export_note(note_id, format="md")
|
|
with open("note.md", "w", encoding="utf-8") as f:
|
|
f.write(content)
|
|
```
|
|
|
|
### 搜尋筆記
|
|
|
|
```python
|
|
results = client.search_notes("關鍵字")
|
|
```
|
|
|
|
### 刪除筆記
|
|
|
|
```python
|
|
client.delete_note(note_id)
|
|
```
|
|
|
|
## 使用 .env 檔案（推薦）
|
|
|
|
建立 `.env` 檔案：
|
|
|
|
```env
|
|
MDCLIENT_URL=https://codimd.lotimmy.com
|
|
MDCLIENT_EMAIL=your@email.com
|
|
MDCLIENT_PASSWORD=your_password
|
|
```
|
|
|
|
在程式碼中使用：
|
|
|
|
```python
|
|
import os
|
|
from dotenv import load_dotenv
|
|
from mdclient import MDAuth, MDClient
|
|
|
|
# 載入環境變數
|
|
load_dotenv()
|
|
|
|
# 登入
|
|
auth = MDAuth(base_url=os.getenv('MDCLIENT_URL'))
|
|
auth.login(
|
|
os.getenv('MDCLIENT_EMAIL'),
|
|
os.getenv('MDCLIENT_PASSWORD')
|
|
)
|
|
|
|
# 使用客戶端
|
|
client = MDClient(base_url=os.getenv('MDCLIENT_URL'))
|
|
notes = client.list_notes()
|
|
```
|
|
|
|
## 連接到不同的伺服器
|
|
|
|
```python
|
|
from mdclient import MDAuth, MDClient
|
|
|
|
# 自訂伺服器
|
|
auth = MDAuth(base_url="https://your-server.com")
|
|
auth.login("user@example.com", "password")
|
|
|
|
client = MDClient(base_url="https://your-server.com")
|
|
notes = client.list_notes()
|
|
```
|
|
|
|
## 完整範例
|
|
|
|
```python
|
|
from mdclient import MDAuth, MDClient
|
|
|
|
# 登入
|
|
auth = MDAuth()
|
|
auth.login("user@example.com", "password")
|
|
|
|
# 建立客戶端
|
|
client = MDClient()
|
|
|
|
# 列出筆記
|
|
notes = client.list_notes()
|
|
print(f"找到 {len(notes)} 筆筆記")
|
|
|
|
# 建立新筆記
|
|
result = client.create_note(
|
|
title="測試筆記",
|
|
content="# 歡迎使用 MDclient\n\n這是一個測試筆記。"
|
|
)
|
|
print(f"建立成功: {result['id']}")
|
|
|
|
# 取得筆記內容
|
|
note = client.get_note(result['id'])
|
|
print(f"筆記標題: {note['title']}")
|
|
|
|
# 匯出筆記
|
|
content = client.export_note(result['id'])
|
|
with open("backup.md", "w", encoding="utf-8") as f:
|
|
f.write(content)
|
|
print("筆記已匯出")
|
|
|
|
# 刪除筆記
|
|
client.delete_note(result['id'])
|
|
print("筆記已刪除")
|
|
```
|
|
|
|
## 下一步
|
|
|
|
- 查看 [API.md](API.md) 了解完整的 API 參考
|
|
- 查看 [auth_example.py](auth_example.py) 了解更多認證範例
|
|
- 查看 [example.py](example.py) 了解更多使用範例
|
|
|
|
## 故障排除
|
|
|
|
### Cookie 過期
|
|
|
|
如果遇到認證失敗，重新登入即可：
|
|
|
|
```python
|
|
auth = MDAuth()
|
|
auth.login("email", "password")
|
|
```
|
|
|
|
### 連接到不同的伺服器
|
|
|
|
```python
|
|
client = MDClient(base_url="https://your-server.com")
|
|
```
|
|
|
|
### 自訂 Cookie 檔案
|
|
|
|
```python
|
|
auth = MDAuth(cookie_file="custom_cookies.conf")
|
|
```
|