David-Li0406/meta-skill-evloving

MarkItDown - 檔案轉 Markdown 轉換

概述

MarkItDown 是微軟開發的 Python 工具，用於將各種檔案格式轉換為 Markdown。它特別適合將文件轉換為對大型語言模型友善的文字格式，因為 Markdown 對 Token 有效率，且現代語言模型能良好理解。

主要優點：

• 將文件轉換為乾淨、結構化的 Markdown
• Token 有效率的格式，適合 LLM 處理
• 支援 15+ 種檔案格式
• 可選 AI 增強的圖片描述
• 圖片與掃描文件的 OCR
• 音訊檔案的語音轉錄

以科學示意圖進行視覺強化

使用此技能建立文件時，務必考慮加入科學圖表與示意圖，以增進視覺溝通。

若您的文件尚未包含示意圖或圖表：

• 使用 scientific-schematics 技能生成 AI 驅動的出版品質圖表
• 只需以自然語言描述您想要的圖表
• Nano Banana Pro 會自動生成、審查並優化示意圖

對於新文件： 預設應生成科學示意圖，以視覺化呈現文字中描述的關鍵概念、工作流程、架構或關係。

如何生成示意圖：

python scripts/generate_schematic.py "您的圖表描述" -o figures/output.png

AI 將自動：

• 建立格式正確的出版品質圖像
• 透過多次迭代審查與優化
• 確保無障礙性（色盲友善、高對比度）
• 將輸出儲存在 figures/ 目錄中

何時加入示意圖：

• 文件轉換工作流程圖
• 檔案格式架構圖解
• OCR 處理管線圖
• 整合工作流程圖
• 系統架構圖
• 資料流程圖
• 任何適合以視覺化呈現的複雜概念

如需建立示意圖的詳細指引，請參閱 scientific-schematics 技能文件。

---

支援的格式

格式	描述	備註
PDF	可攜式文件格式	完整文字提取
DOCX	Microsoft Word	保留表格、格式
PPTX	PowerPoint	投影片含備註
XLSX	Excel 試算表	表格與資料
圖片	JPEG、PNG、GIF、WebP	EXIF 元資料 + OCR
音訊	WAV、MP3	元資料 + 轉錄
HTML	網頁	乾淨轉換
CSV	逗號分隔值	表格格式
JSON	JSON 資料	結構化表示
XML	XML 文件	結構化格式
ZIP	壓縮檔	遍歷內容
EPUB	電子書	完整文字提取
YouTube	影片網址	擷取轉錄

快速開始

安裝

# 安裝所有功能
pip install 'markitdown[all]'

# 或者從原始碼安裝
git clone https://github.com/microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

命令列使用

# 基本轉換
markitdown document.pdf > output.md

# 指定輸出檔案
markitdown document.pdf -o output.md

# 管道內容
cat document.pdf | markitdown > output.md

# 啟用外掛程式
markitdown --list-plugins  # 列出可用的外掛程式
markitdown --use-plugins document.pdf -o output.md

Python API

from markitdown import MarkItDown

# 基本使用
md = MarkItDown()
result = md.convert("document.pdf")
print(result.text_content)

# 從串流轉換
with open("document.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    print(result.text_content)

進階功能

1. AI 增強的圖片描述

經由 OpenRouter 使用 LLM 生成詳細的圖片描述（適用於 PPTX 和圖片檔案）：

from markitdown import MarkItDown
from openai import OpenAI

# 初始化 OpenRouter 客戶端（OpenAI 相容 API）
client = OpenAI(
    api_key="您的-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",  # 推薦用於科學視覺
    llm_prompt="詳細描述此圖片以用於科學文件"
)

result = md.convert("presentation.pptx")
print(result.text_content)

2. Azure Document Intelligence

使用 Microsoft Document Intelligence 進行增強的 PDF 轉換：

# 命令列
markitdown document.pdf -o output.md -d -e "<document_intelligence_endpoint>"

# Python API
from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("complex_document.pdf")
print(result.text_content)

3. 外掛程式系統

MarkItDown 支援第三方外掛程式來擴充功能：

# 列出已安裝的外掛程式
markitdown --list-plugins

# 啟用外掛程式
markitdown --use-plugins file.pdf -o output.md

在 GitHub 上使用標籤尋找外掛程式：#markitdown-plugin

選擇性依賴項

控制您要支援的檔案格式：

# 安裝特定格式
pip install 'markitdown[pdf, docx, pptx]'

# 所有可用選項：
# [all]                  - 所有選擇性依賴項
# [pptx]                 - PowerPoint 檔案
# [docx]                 - Word 文件
# [xlsx]                 - Excel 試算表
# [xls]                  - 較舊的 Excel 檔案
# [pdf]                  - PDF 文件
# [outlook]              - Outlook 郵件
# [az-doc-intel]         - Azure Document Intelligence
# [audio-transcription]  - WAV 和 MP3 轉錄
# [youtube-transcription] - YouTube 影片轉錄

常見使用案例

1. 將科學論文轉換為 Markdown

from markitdown import MarkItDown

md = MarkItDown()

# 轉換 PDF 論文
result = md.convert("research_paper.pdf")
with open("paper.md", "w") as f:
    f.write(result.text_content)

2. 從 Excel 提取資料進行分析

from markitdown import MarkItDown

md = MarkItDown()
result = md.convert("data.xlsx")

# 結果將為 Markdown 表格格式
print(result.text_content)

3. 處理多個文件

from markitdown import MarkItDown
import os
from pathlib import Path

md = MarkItDown()

# 處理目錄中所有 PDF
pdf_dir = Path("papers/")
output_dir = Path("markdown_output/")
output_dir.mkdir(exist_ok=True)

for pdf_file in pdf_dir.glob("*.pdf"):
    result = md.convert(str(pdf_file))
    output_file = output_dir / f"{pdf_file.stem}.md"
    output_file.write_text(result.text_content)
    print(f"已轉換：{pdf_file.name}")

4. 轉換 PowerPoint 並加入 AI 描述

from markitdown import MarkItDown
from openai import OpenAI

# 使用 OpenRouter 存取多個 AI 模型
client = OpenAI(
    api_key="您的-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",  # 推薦用於簡報
    llm_prompt="詳細描述此投影片圖片，重點關注關鍵視覺元素與資料"
)

result = md.convert("presentation.pptx")
with open("presentation.md", "w") as f:
    f.write(result.text_content)

5. 批次轉換不同格式

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# 要轉換的檔案
files = [
    "document.pdf",
    "spreadsheet.xlsx",
    "presentation.pptx",
    "notes.docx"
]

for file in files:
    try:
        result = md.convert(file)
        output = Path(file).stem + ".md"
        with open(output, "w") as f:
            f.write(result.text_content)
        print(f"✓ 已轉換 {file}")
    except Exception as e:
        print(f"✗ 轉換 {file} 時發生錯誤：{e}")

6. 提取 YouTube 影片轉錄

from markitdown import MarkItDown

md = MarkItDown()

# 將 YouTube 影片轉換為逐字稿
result = md.convert("https://www.youtube.com/watch?v=VIDEO_ID")
print(result.text_content)

Docker 使用

# 建置映像檔
docker build -t markitdown:latest .

# 執行轉換
docker run --rm -i markitdown:latest < ~/document.pdf > output.md

最佳實踐

1. 選擇正確的轉換方法

• 簡單文件：使用基本 MarkItDown()
• 複雜 PDF：使用 Azure Document Intelligence
• 視覺內容：啟用 AI 圖片描述
• 掃描文件：確保已安裝 OCR 依賴項

2. 優雅地處理錯誤

from markitdown import MarkItDown

md = MarkItDown()

try:
    result = md.convert("document.pdf")
    print(result.text_content)
except FileNotFoundError:
    print("檔案未找到")
except Exception as e:
    print(f"轉換錯誤：{e}")

3. 高效處理大型檔案

from markitdown import MarkItDown

md = MarkItDown()

# 對於大型檔案，使用串流
with open("large_file.pdf", "rb") as f:
    result = md.convert_stream(f, file_extension=".pdf")
    
    # 分塊處理或直接儲存
    with open("output.md", "w") as out:
        out.write(result.text_content)

4. 針對 Token 效率最佳化

Markdown 輸出已具備 Token 效率，但您可以：

• 移除過多的空白
• 合併相似章節
• 如不需要則移除元資料

from markitdown import MarkItDown
import re

md = MarkItDown()
result = md.convert("document.pdf")

# 清理多餘空白
clean_text = re.sub(r'\n{3,}', '\n\n', result.text_content)
clean_text = clean_text.strip()

print(clean_text)

與科學工作流程的整合

轉換文獻以供審查

from markitdown import MarkItDown
from pathlib import Path

md = MarkItDown()

# 轉換 literature 資料夾中所有論文
papers_dir = Path("literature/pdfs")
output_dir = Path("literature/markdown")
output_dir.mkdir(exist_ok=True)

for paper in papers_dir.glob("*.pdf"):
    result = md.convert(str(paper))
    
    # 儲存含元資料
    output_file = output_dir / f"{paper.stem}.md"
    content = f"# {paper.stem}\n\n"
    content += f"**來源**：{paper.name}\n\n"
    content += "---\n\n"
    content += result.text_content
    
    output_file.write_text(content)

# 使用 AI 增強的圖形轉換
from openai import OpenAI

client = OpenAI(
    api_key="您的-openrouter-api-key",
    base_url="https://openrouter.ai/api/v1"
)

md_ai = MarkItDown(
    llm_client=client,
    llm_model="anthropic/claude-sonnet-4.5",
    llm_prompt="以技術精確度描述科學圖形"
)

提取表格進行分析

from markitdown import MarkItDown
import re

md = MarkItDown()
result = md.convert("data_tables.xlsx")

# Markdown 表格可直接解析或使用
print(result.text_content)

疑難排解

常見問題

1. 缺少依賴項：安裝特定功能套件

   pip install 'markitdown[pdf]'  # 用於 PDF 支援
   

2. 二進位檔案錯誤：確保以二進位模式開啟檔案

   with open("file.pdf", "rb") as f:  # 注意是 "rb"
       result = md.convert_stream(f, file_extension=".pdf")
   

3. OCR 無法運作：安裝 tesseract

   # macOS
   brew install tesseract
   
   # Ubuntu
   sudo apt-get install tesseract-ocr
   

效能考量

• PDF 檔案：大型 PDF 可能耗時；若支援，可考慮指定頁面範圍
• 圖片 OCR：OCR 處理為 CPU 密集型
• 音訊轉錄：需要額外的運算資源
• AI 圖片描述：需要 API 呼叫（可能產生費用）

後續步驟

• 參閱 references/api_reference.md 了解完整的 API 文件
• 檢查 references/file_formats.md 了解格式特定細節
• 查看 scripts/batch_convert.py 了解自動化範例
• 探索 scripts/convert_with_ai.py 了解 AI 增強的轉換

資源

• MarkItDown GitHub：https://github.com/microsoft/markitdown
• PyPI：https://pypi.org/project/markitdown/
• OpenRouter：https://openrouter.ai （適用於 AI 增強的轉換）
• OpenRouter API 金鑰：https://openrouter.ai/keys
• OpenRouter 模型：https://openrouter.ai/models
• MCP 伺服器：markitdown-mcp（適用於 Claude Desktop 整合）
• 外掛程式開發：參閱 packages/markitdown-sample-plugin