GroupDocs.Markdown for Python via .NET — 將文件匯出為 Markdown

將您的文件直接帶入 AI 流程 — 從 Python、本地部署，只需一次 pip install。

今天，我們在 PyPI 上發布了 GroupDocs.Markdown for Python via .NET 的首個公開發行版。此函式庫可將 PDF、Word、Excel、EPUB 以及 20 多種其他格式轉換為乾淨、語義化的 Markdown —— 這是 LLM、RAG 流程以及靜態網站生成器最適合的格式。

如果您已關注過九月的 .NET 發行版（或 26.3 中的完整 API 大改版），其背後的理由相同：文件格式承載語義，保留這些語義結構才能讓 RAG 系統給出良好的答案。前文已深入探討問題（OCR 會扁平化結構，LLM 需要 Markdown）和 解決方案（基於 DOM 的渲染器遍歷文件並輸出 Markdown）——此處不再重複。

下面，我們聚焦於 Python 開發者的新功能。

您將獲得什麼

單一 wheel，無執行時相依。pip install groupdocs-markdown-net 會下載一個自包含的 wheel，內含 .NET 執行時與所有必需的原生函式庫。無需安裝 dotnet、Microsoft Office、Adobe Acrobat，也不依賴雲端服務。
跨平台。支援 Windows x64/x86、Linux x64、macOS x64 以及 Apple Silicon (ARM64)。支援 Python 3.5 至 3.14。
Pythonic API。類別使用 PascalCase，方法與屬性使用 snake_case，列舉值使用 UPPER_SNAKE_CASE。Context manager 可決定性地釋放已載入的文件。
真正的非同步。每個靜態與實例方法都有 _async 版本。檔案 I/O 為非同步，CPU 密集的轉換則在工作執行緒上執行 —— 您的 asyncio 事件迴圈保持空閒。
AI 代理友好。安裝的 wheel 內含 AGENTS.md，讓編碼助理（Claude Code、Cursor、GitHub Copilot、Codex）自動發現 API、慣用用法與故障排除技巧。文件同時以 llms.txt、單檔語料庫 (llms-full.txt)、每頁 Markdown 以及 MCP 伺服器形式發布 —— 詳情請見下方 AI-friendly by design。

快速開始

pip install groupdocs-markdown-net

最簡單的轉換只需一行程式碼：

from groupdocs.markdown import MarkdownConverter

# 轉換為字串
md = MarkdownConverter.to_markdown("business-plan.docx")

# 或直接寫入檔案
MarkdownConverter.to_file("business-plan.docx", "business-plan.md")

就是這麼簡單 —— 無需設定、無需選項、無需樣板程式碼。評估模式只會處理前 3 頁並加上浮水印。若要解除限制，請套用授權：

from groupdocs.markdown import License

License().set_license("path/to/license.lic")

或將 GROUPDOCS_LIC_PATH 設為環境變數，匯入時會自動套用。

支援的格式

Python 套件支援的格式與 .NET 函式庫相同：

PDF — .pdf
Word / Rich Text — .doc, .docx, .docm, .dot, .dotx, .dotm, .rtf, .odt, .ott
試算表 — .xls, .xlsx, .xlsb, .xlsm, .csv, .tsv, .ods, .ots
電子書 — .epub, .mobi
文字 / 標記 / 說明檔 — .txt, .xml, .chm

Pythonic 範例

轉換選項與圖片策略

from groupdocs.markdown import (
    MarkdownConverter,
    ConvertOptions,
    MarkdownFlavor,
    ExportImagesToFileSystemStrategy,
)

strategy = ExportImagesToFileSystemStrategy("output/images")
strategy.images_relative_path = "images"  # ![](images/img-001.png)

options = ConvertOptions()
options.flavor = MarkdownFlavor.GIT_HUB
options.heading_level_offset = 1      # # Title -> ## Title
options.include_front_matter = True    # 前置 YAML 中繼資料
options.image_export_strategy = strategy

MarkdownConverter.to_file("report.docx", "output/report.md", convert_options=options)

不轉換的文件檢查

from groupdocs.markdown import MarkdownConverter

info = MarkdownConverter.get_info("business-plan.docx")
print(f"{info.file_format}, {info.page_count} pages, author: {info.author}")

載入受密碼保護的檔案

from groupdocs.markdown import MarkdownConverter, LoadOptions, FileFormat

load_opts = LoadOptions(FileFormat.DOCX)
load_opts.password = "secret"

MarkdownConverter.to_file("protected.docx", "output.md", load_options=load_opts)

串流與 Context Manager

from groupdocs.markdown import MarkdownConverter

with open("document.docx", "rb") as stream:
    with MarkdownConverter(stream) as converter:
        converter.convert("document.md")

Async API — 同時轉換多個文件

由於檔案 I/O 為非同步，asyncio.gather() 可讓單一工作執行緒同時處理多個文件而不會阻塞：

import asyncio
from groupdocs.markdown import MarkdownConverter

async def convert_many():
    await asyncio.gather(
        MarkdownConverter.to_file_async("a.docx", "a.md", None),
        MarkdownConverter.to_file_async("b.pdf",  "b.md", None),
        MarkdownConverter.to_file_async("c.xlsx", "c.md", None),
    )

asyncio.run(convert_many())

這使得函式庫非常適合 FastAPI 等 ASGI 框架 —— 單一工作者即可服務多個同時的轉換請求，無需執行緒競爭。

錯誤處理

所有轉換方法在失敗時都會拋出例外，且針對常見情況提供特定例外類型：

from groupdocs.markdown import (
    MarkdownConverter,
    DocumentProtectedException,
    InvalidFormatException,
    GroupDocsMarkdownException,
)

try:
    MarkdownConverter.to_file("annual-report.docx", "annual-report.md")
except DocumentProtectedException:
    print("密碼錯誤或缺失。")
except InvalidFormatException:
    print("檔案損毀或不支援的格式。")
except GroupDocsMarkdownException as ex:
    print(f"轉換失敗: {ex}")

為 RAG 與 LLM 流程而建

Markdown 是嵌入模型與檢索流程的首選輸入格式 —— 它保留標題、清單、表格與強調，同時易於切塊與斷詞。典型的 RAG 資料攝取流程如下：

import re
from groupdocs.markdown import MarkdownConverter, ConvertOptions, SkipImagesStrategy, MarkdownFlavor

options = ConvertOptions()
options.image_export_strategy = SkipImagesStrategy()   # 只保留文字，適用於 RAG
options.flavor = MarkdownFlavor.COMMON_MARK

MarkdownConverter.to_file("business-plan.pdf", "business-plan.md", convert_options=options)

with open("business-plan.md", "r", encoding="utf-8") as f:
    markdown = f.read()

# 以頂層標題切分，然後對每個片段進行嵌入/索引
chunks = [c for c in re.split(r"\n#{1,2} ", markdown) if c.strip()]

因為函式庫完全在本地執行，敏感文件永不離開您的環境 —— 這是受管制產業、法律團隊與內部知識庫的常見需求。

AI-friendly by design

大多數 Python SDK 把 AI 編碼助理視為事後考量 —— 開發者仍需自行指向文件、貼上範例或透過試錯除錯。GroupDocs.Markdown for Python via .NET 則相反：此函式庫的設計讓 Claude Code、Cursor、GitHub Copilot、Codex 等助理能在無需手動設定的情況下直接使用。

`AGENTS.md` 隨 wheel 一起發佈

這是首個在安裝的 wheel 內直接捆帶 AGENTS.md 檔案的 GroupDocs 套件。該檔案遵循新興的 AGENTS.md 規範 —— 一份專為 AI 編碼助理而非人類閱讀撰寫的純 Markdown README。

執行 pip install groupdocs-markdown-net 後，檔案會出現在：

site-packages/groupdocs/markdown/AGENTS.md

AI 助理打開您的專案時即可讀取，立即學會：

完整的 公開 API 表面（類別、方法、列舉、例外）以及它們之間的關係。
最常見情境的 慣用使用模式 —— 靜態 vs 實例 API、同步 vs 非同步、圖片策略、前置中繼資料、錯誤處理。
常見陷阱 以及避免方法 —— 例如哪些 ConvertOptions 重載接受 None、如何處理受密碼保護的檔案、如何捕捉轉換警告。
平台特定問題的故障排除（macOS 上的 libSkiaSharp、Linux 上的 ICU）。

實務上，您只要說 「使用 groupdocs-markdown-net 把這個 PDF 資料夾轉成 Markdown 供我的 RAG 流程使用」，助理即可在第一次嘗試就寫出可執行的程式碼 —— 不會產生幻覺式的方法名稱、錯誤的參數順序或猜測的匯入語句。

機器可讀文件

若助理需要查找 AGENTS.md 未涵蓋的資訊，完整的產品文件也以機器可讀形式發布：

單檔語料庫 —— 完整文件合併為一個 Markdown 檔，直接放入助理的上下文視窗：
https://docs.groupdocs.com/markdown/python-net/llms-full.txt
每頁 Markdown —— 在任意文件 URL 後加上 .md 即可取得原始來源：
https://docs.groupdocs.com/markdown/python-net/quick-start-guide.md
llms.txt 索引 —— 一個符合 llms.txt 風格的目錄，指向助理需要的頁面：
https://docs.groupdocs.com/markdown/python-net/llms.txt

MCP 伺服器供即時文件查詢

對於支援 Model Context Protocol 的助理，我們提供 MCP 伺服器。將以下設定加入您的 Claude Code 或 Cursor 配置：

{
  "mcpServers": {
    "groupdocs-docs": {
      "url": "https://docs.groupdocs.com/mcp"
    }
  }
}

之後，助理即可按需查詢文件，而不必依賴可能已過時的訓練資料。

Markdown 輸入、Markdown 輸出

此處有一個美好的對稱性：函式庫的輸出為 Markdown —— LLM 最擅長解析的 RAG 格式 —— 而其文件也同樣以 Markdown 提供，作為單檔供上下文窗口輕鬆 ingest。無論您是請助理撰寫使用函式庫的程式碼，或是請助理透過函式庫「理解」您的文件，Markdown 都是共同的媒介。

匯出範例

上面的程式碼片段已相當接近您能寫出的最短實用程式。以下示範將相同概念打包成可執行的專案 —— 包含原始文件、Python 腳本、預先產生的輸出、requirements.txt 與 Dockerfile —— 讓您可以端到端測試，且無需從頭編寫任何程式。

原始 DOCX

原始檔案 business-plan.docx 為一份短小、格式豐富的商業計畫書，內含標題、表格、圖片與中繼資料。

Python 腳本

from groupdocs.markdown import MarkdownConverter, ConvertOptions, MarkdownFlavor

def quick_example():
    """將 Word 文件轉為 GitHub 風格的 Markdown，並加入 YAML 前置中繼資料。"""

    # 一行程式碼 —— 回傳 Markdown 字串
    md = MarkdownConverter.to_markdown("business-plan.docx")

    # 使用選項 —— 寫入檔案
    options = ConvertOptions()
    options.flavor = MarkdownFlavor.GIT_HUB
    options.include_front_matter = True
    options.heading_level_offset = 1
    MarkdownConverter.to_file("business-plan.docx", "quick-example.md", convert_options=options)

if __name__ == "__main__":
    quick_example()

輸出 Markdown

quick-example.md 的輸出以自動從文件中抽取的 YAML 前置中繼資料區塊開頭，接著是使用 GitHub Flavored 表格與調整過的標題層級的轉換內容（可直接嵌入更大的文件中）。

可執行的範例應用

全部打包在一起： sample-app.zip。解壓後執行：

cd src
python -m venv .venv
# Windows: .venv\Scripts\activate
# Linux/macOS: source .venv/bin/activate
pip install -r requirements.txt
python quick_example.py

或使用 Docker —— 隨附的 Dockerfile 會在 Linux 上安裝 .NET 執行時所需的 ICU 依賴：

cd src
docker build -t groupdocs-markdown-python-example .
docker run --rm -v "$(pwd)/output:/app/output" groupdocs-markdown-python-example

總結

GroupDocs.Markdown for Python via .NET 將完整的文件轉 Markdown 引擎以自包含的 wheel 形式帶到 Python —— 無需外部執行時、無需雲端、無意外驚喜。Pythonic API、非同步支援與一流的 AI 工具整合，使其成為 Python 團隊構建 RAG 系統、靜態網站生成器或文件處理流水線的實用選擇。

了解更多

PyPI 套件：https://pypi.org/project/groupdocs-markdown-net/
產品首頁：https://products.groupdocs.com/markdown/python-net/
文件中心：https://docs.groupdocs.com/markdown/python-net/
版本說明：https://releases.groupdocs.com/markdown/python-net/release-notes/
GitHub 程式碼範例：https://github.com/groupdocs-markdown/GroupDocs.Markdown-for-Python-via-.NET
授權資訊：https://about.groupdocs.com/legal/
相關 .NET 發布文章： GroupDocs.Markdown for .NET — First Public Release

支援與回饋

如有任何問題或需要技術協助，請前往我們的 Free Support Forum —— 我們很樂意為您服務。

您將獲得什麼#

快速開始#

支援的格式#

Pythonic 範例#

轉換選項與圖片策略#

不轉換的文件檢查#

載入受密碼保護的檔案#

串流與 Context Manager#

Async API — 同時轉換多個文件#

錯誤處理#

為 RAG 與 LLM 流程而建#

AI-friendly by design#

AGENTS.md 隨 wheel 一起發佈#

機器可讀文件#

MCP 伺服器供即時文件查詢#

Markdown 輸入、Markdown 輸出#

匯出範例#

總結#

了解更多#

支援與回饋#