MarkItDown - 파일을 마크다운으로 변환

MarkItDown - 파일을 마크다운으로 변환은(는) 무엇을 하나요?

개요

MarkItDown은 Microsoft에서 개발한 Python 도구로, 다양한 파일 형식을 마크다운(Markdown)으로 변환합니다. 특히 문서를 LLM 친화적인 텍스트 형식으로 변환하는 데 유용합니다. 마크다운은 토큰 효율성이 높고 최신 언어 모델이 잘 이해하는 형식이기 때문입니다.

주요 장점:

• 문서를 깔끔하고 구조화된 마크다운으로 변환
• 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	비디오 URL	자막 가져오기

빠른 시작

설치

# 모든 기능 설치
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="your-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. 과학 논문을 마크다운으로 변환

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

# 결과는 마크다운 테이블 형식입니다
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. AI 설명과 함께 PowerPoint 변환

from markitdown import MarkItDown
from openai import OpenAI

# 여러 AI 모델에 접근하기 위해 OpenRouter 사용
client = OpenAI(
    api_key="your-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. 토큰 효율성 최적화

마크다운 출력은 이미 토큰 효율적이지만, 다음과 같은 방법으로 더 최적화할 수 있습니다:

• 과도한 공백 제거
• 유사한 섹션 통합
• 필요하지 않은 경우 메타데이터 제거

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

# 문헌 폴더의 모든 논문 변환
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="your-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")

# 마크다운 표는 파싱하거나 직접 사용할 수 있습니다
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 호출이 필요합니다 (비용이 발생할 수 있음).

다음 단계

• 전체 API 문서는 references/api_reference.md를 참조하세요.
• 형식별 세부 사항은 references/file_formats.md를 확인하세요.
• 자동화 예제는 scripts/batch_convert.py를 검토하세요.
• AI 기반 변환은 scripts/convert_with_ai.py를 살펴보세요.

리소스

• 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 참조