helper-md-doc

Markdown/HTML을 DOCX로 변환하는 Python 라이브러리 (Mermaid 다이어그램 및 LaTeX 수식 지원)

주요 기능

• Markdown → HTML 변환: Mermaid 다이어그램과 LaTeX 수식을 PNG 이미지로 렌더링
• HTML → DOCX 변환: 이미지와 수식을 임베딩하여 DOCX 생성
• Markdown → DOCX 직접 변환: 원스텝 변환 지원
• Mermaid 지원: 플로우차트, 시퀀스 다이어그램 등 자동 렌더링
• LaTeX 수식 지원: KaTeX 기반 수식 렌더링
• 이미지 임베딩: Base64 인코딩 또는 파일 경로 지원

설치

기본 설치

pip install helper-md-doc

# 테스트 서버
pip install --index-url https://test.pypi.org/simple/ helper-md-doc

Playwright 브라우저 설치 (필수)

playwright install chromium

Pandoc 설치 (필수)

• Windows: https://pandoc.org/installing.html
• Mac: brew install pandoc
• Linux: sudo apt-get install pandoc

사용법

1. Markdown → HTML 변환

from helper_md_doc import md_to_html

md_text = """
# 제목

이것은 **Markdown** 문서입니다.

## Mermaid 다이어그램
```mermaid
graph LR
    A[시작] --> B[처리]
    B --> C[종료]

LaTeX 수식

인라인 수식: $E = mc^2$

블록 수식: $$ \frac{-b \pm \sqrt{b^2 - 4ac}}{2a} $$ """

html = md_to_html(md_text, title="문서 제목", use_base64=True) print(html)

### 2. HTML → DOCX 변환

```python
from helper_md_doc import html_to_doc

html_to_doc("input.html", "output.docx")

3. Markdown → DOCX 직접 변환

from helper_md_doc import md_to_doc

md_to_doc("input.md", "output.docx", title="문서 제목")

4. 역방향 변환

from helper_md_doc import doc_to_html, html_to_md, md_to_text

# DOCX → HTML (이미지 base64 임베딩)
doc_to_html("input.docx", "output.html")

# HTML → Markdown
html_to_md("input.html", "output.md")

# HTML → GitHub Flavored Markdown
html_to_md("input.html", "output.md", md_variant="gfm")

# Markdown → 순수 텍스트 (수식 제거)
md_to_text("input.md", "output.txt")

# Markdown → 순수 텍스트 (수식 원문 유지)
md_to_text("input.md", "output.txt", keep_math=True)

5. CLI 사용

# Markdown → HTML
md2html input.md -o output.html --base64

# HTML → DOCX
html2doc input.html -o output.docx

# Markdown → DOCX
md2doc input.md -o output.docx --title "문서 제목"

# Markdown → PDF
md2pdf input.md -o output.pdf

# HTML → PDF
html2pdf input.html -o output.pdf

# DOCX → HTML (역변환)
doc2html input.docx -o output.html

# DOCX → HTML (이미지 별도 파일)
doc2html input.docx --no-embed

# HTML → Markdown (역변환)
html2md input.html -o output.md

# HTML → GitHub Flavored Markdown
html2md input.html --variant gfm

# Markdown → 순수 텍스트 (역변환)
md2text input.md -o output.txt

# Markdown → 순수 텍스트 (수식 원문 유지)
md2text input.md --keep-math

또는 모듈로 실행:

# Markdown → HTML
python -m helper_md_doc.helper_md_html input.md -o output.html --base64

# HTML → DOCX
python -m helper_md_doc.helper_html_doc input.html -o output.docx

# Markdown → DOCX
python -m helper_md_doc.helper_md_doc input.md -o output.docx --title "문서 제목"

# DOCX → HTML (역변환)
python -m helper_md_doc.helper_doc_html input.docx -o output.html

# HTML → Markdown (역변환)
python -m helper_md_doc.helper_html_md input.html -o output.md

# Markdown → 순수 텍스트 (역변환)
python -m helper_md_doc.helper_md_text input.md -o output.txt

의존성

• markdown (>=3.7.0): Markdown 파싱
• playwright (>=1.40.0): Mermaid/LaTeX 렌더링
• pypandoc (>=1.13): DOCX 변환

개발

# 저장소 클론
git clone https://github.com/c0z0c-helper/helper_md_doc.git
cd helper_md_doc

# 편집 모드 설치
pip install -e .

# 개발 의존성 설치
pip install -r requirements-dev.txt

# 테스트 실행
pytest

라이센스

MIT License

본 패키지는 다음 서드파티 라이브러리를 포함합니다:

• KaTeX (MIT License) - LaTeX 수식 렌더링
• KaTeX Fonts (SIL Open Font License 1.1) - 수식용 폰트
• Mermaid (MIT License) - 다이어그램 렌더링

자세한 내용은 THIRD_PARTY_LICENSES.md를 참조하세요.

기여

버그 리포트나 기능 제안은 GitHub Issues에 등록해주세요.

변경 이력

v0.5.1(2025-12-09)

• 최초 릴리스

v0.5.2(2025-12-09)

• BOM 처리
• ** 속성 적용

v0.5.5(2025-12-11)

• 종속 라이브러리 설치

v0.5.6(2026-03-19)

• 랜더링 최적화

v0.5.8(2026-03-21)

• doc 변환시 기본 폰트 D2Coding 적용
• D2Coding 폰트 자동 설치

v0.5.9(2026-04-18)

• HTML → PDF 변환 기능 추가
• Markdown → PDF 변환 기능 추가
• html2pdf, md2pdf CLI 추가

v0.5.11(2026-05-01)

• math_mode 기본값 변경: omml → mathml (세부 튜닝 가능, 품질 향상)
• 역방향 변환 기능 추가
  • DOCX → HTML 변환 (doc_to_html, doc2html CLI)
  • HTML → Markdown 변환 (html_to_md, html2md CLI)
  • Markdown → 순수 텍스트 변환 (md_to_text, md2text CLI)

v0.5.13(2026-05-09)

• HTML → PDF 변환 기능 개선
• Markdown → PDF 변환 기능 개선
• 누락 라이브러리 감지 및 설치 안내 기능 추가

v0.5.15(2026-05-17)

• 수식 랜더링 docx 변환시 mathml → omml로 변경 (품질 향상)
• table outline 개선

v0.5.16(2026-05-23)

• PDF 출력 품질 개선: 폰트 크기 체계(본문 10pt, h1h6 1116pt), 여백, 테이블·코드블록 CSS 정비
• 이미지 상대경로 문제 수정: md 파일 위치 기준으로 이미지 탐색 (md_dir 파라미터 추가)
• DOCX 변환 시 이미지 정상 포함

v0.6.0(2026-06-29)

• md2doc 테이블 셀 단락에 "In Table" 스타일 적용

v0.6.1(2027-07-17)

• 개발환경 uv 전환

v0.6.2(2026-09-10)

• Playwright 드라이버 중복 기동 문제 수정: 서브모듈마다 requirements_rnac를 별도로 로드하던 구조를 공유 모듈 임포트로 변경하여, md2doc 실행 시 8회 반복되던 Task was destroyed but it is pending! / TargetClosedError 경고 제거
• pandoc 실행 파일 자동 확인/설치 추가: pypandoc은 설치되어 있으나 pandoc 바이너리가 없는 환경(새 PC 등)에서 OSError: No pandoc was found로 실패하던 문제 수정. 종속성 확인 시 pandoc 미탐지 시 pypandoc.download_pandoc()으로 자동 설치

v0.6.3(2026-09-12)

• 경고 로그 출력 개선