MDclient

Markdown 筆記服務的 Python 客戶端函式庫。

支援 CodiMD、HedgeDoc、HackMD 等服務。

特色

• ✅ 簡單好用的 Python API
• ✅ 支援多種 Markdown 筆記服務
• ✅ 自動會話管理（Cookie）
• ✅ 支援 .env 設定檔
• ✅ 完整的筆記操作（建立、讀取、更新、刪除、匯出）

安裝

pip install mdclient

如果需要 .env 支援：

pip install "mdclient[env]"

快速開始

from mdclient import MDClient, MDAuth

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

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

for note in notes:
    print(f"{note['text']} - {note['id']}")

主要功能

列出筆記

client = MDClient()
notes = client.list_notes()

建立筆記

result = client.create_note("標題", "# 內容")

取得筆記

note = client.get_note(note_id)
print(note['content'])

匯出筆記

content = client.export_note(note_id, format="md")

搜尋筆記

results = client.search_notes("關鍵字")

刪除筆記

client.delete_note(note_id)

使用 .env 檔案

建立 .env 檔案：

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

在程式碼中使用：

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()

自訂伺服器

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()

CLI 工具（可選）

專案包含一個可選的 CLI 工具：

# 登入
python3 mdclient_cli.py login

# 列出筆記
python3 mdclient_cli.py list

# 建立筆記
python3 mdclient_cli.py create "標題"

# 取得筆記
python3 mdclient_cli.py get <note_id>

# 匯出筆記
python3 mdclient_cli.py export <note_id> -o note.md

API 參考

詳細的 API 文件請查看 API.md。

範例

• example.py - 基本使用範例
• auth_example.py - 認證功能範例

專案結構

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          # 本檔案

環境變數

• MDCLIENT_URL - 伺服器位址
• MDCLIENT_EMAIL - 登入信箱
• MDCLIENT_PASSWORD - 登入密碼
• MDCLIENT_COOKIE_FILE - Cookie 檔案路徑

開發

# 安裝開發依賴
pip install -e ".[dev]"

# 執行測試
pytest

# 程式碼格式化
black mdclient/

# 型別檢查
mypy mdclient/

授權

MIT