Skip to content
BranchesTags

Repository files navigation

HWP2MD

Test Lint PyPI npm License: MIT

Convert Korean HWP 5.0 and HWPX documents to LLM-optimized Markdown

A library and CLI tool that converts Hancom HWP (5.0 binary) and HWPX (ZIP+XML) files into clean Markdown. Extracts text, tables, and document structure while preserving semantic information.

  • Python package on PyPI | JavaScript/TypeScript package on npm
  • Supports both HWP 5.0 (OLE Compound File) and HWPX (Open XML) formats
  • Table extraction with cell merge handling (rowspan/colspan)
  • Works in Node.js, browsers, and Python 3.12+
# Python
uvx hwp2md convert input.hwp output.md

# JavaScript
npx hwp2md convert input.hwpx output.md

한국어 문서는 아래에 있습니다

HWP 5.0 및 HWPX 문서를 LLM에 최적화된 Markdown으로 변환

HWP2MD는 한글(HWP 5.0 및 HWPX) 파일을 깔끔한 Markdown으로 변환하는 라이브러리 및 CLI 도구입니다. 텍스트, 표, 문서 구조를 추출하며 의미 정보를 보존합니다.

두 가지 구현체 제공:

주요 기능

  • 🚀 빠르고 정확 - HWP 5.0 바이너리 및 HWPX(ZIP+XML) 직접 파싱
  • 📊 표 지원 - 셀 병합 처리를 포함한 표 추출
  • 🤖 LLM 최적화 - AI 처리에 최적화된 깔끔한 텍스트 출력
  • 🎨 유연한 출력 - 용도에 맞는 포맷 설정
  • 💻 CLI & 라이브러리 - 커맨드라인 도구 또는 라이브러리로 사용
  • 📝 순수 Markdown - HTML 변환 없이 순수 Markdown 출력
  • 🌐 멀티 플랫폼 - Python, Node.js, 브라우저에서 동작
  • 📦 TypeScript 지원 - 전체 타입 정의 포함
  • 📄 HWP & HWPX - 두 가지 한글 파일 형식 모두 지원

설치

Python

# uvx 사용 (권장)
uvx hwp2md input.hwp

# pip 사용
pip install hwp2md

# 소스에서 설치
cd packages/python
uv pip install -e .

JavaScript/TypeScript

# npm
npm install hwp2md

# pnpm
pnpm add hwp2md

# yarn
yarn add hwp2md

# 전역 CLI 설치
npm install -g hwp2md

빠른 시작

커맨드라인 (Python & JavaScript 공통)

# HWP를 Markdown으로 변환
hwp2md convert input.hwp output.md

# HWPX를 Markdown으로 변환 (자동 감지)
hwp2md convert input.hwpx output.md

# 표 내 줄바꿈을 <br>로 표시
hwp2md convert input.hwp output.md --table-line-breaks=br

# 파일 정보 표시
hwp2md info input.hwp
hwp2md info input.hwpx

Python 라이브러리

from hwp2md.parser import HWPFile
from hwp2md.converter import convert_hwp_to_markdown

# HWP 변환
with HWPFile('input.hwp') as hwp:
    markdown = convert_hwp_to_markdown(hwp)
    print(markdown)

# HWPX 변환
from hwp2md.hwpx_parser import HWPXFile
from hwp2md.converter import convert_hwpx_to_markdown

with HWPXFile('input.hwpx') as hwpx:
    markdown = convert_hwpx_to_markdown(hwpx)
    print(markdown)

# 옵션 지정 (HWP/HWPX 동일)
with HWPFile('input.hwp') as hwp:
    markdown = convert_hwp_to_markdown(
        hwp,
        table_line_break_style='br'  # 'space' (기본값) 또는 'br'
    )

JavaScript/TypeScript

Node.js:

import { convert } from 'hwp2md';

// HWP 또는 HWPX 변환 (자동 감지)
const markdown = await convert('input.hwp');   // HWP
const markdown2 = await convert('input.hwpx'); // HWPX

// 옵션 지정
const markdown3 = await convert('input.hwp', {
  tableLineBreakStyle: 'br'  // 'space' (기본값) 또는 'br'
});

브라우저:

import { convertFromFile } from 'hwp2md/browser';

const fileInput = document.getElementById('file') as HTMLInputElement;
fileInput.addEventListener('change', async (e) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (file) {
    const markdown = await convertFromFile(file);
    console.log(markdown);
  }
});

CLI 레퍼런스

convert

HWP/HWPX 파일을 Markdown으로 변환합니다.

hwp2md convert [OPTIONS] INPUT_FILE [OUTPUT_FILE]

인자:

  • INPUT_FILE - HWP 또는 HWPX 파일 경로 (확장자로 자동 감지)
  • OUTPUT_FILE - 출력 Markdown 파일 (생략 시 입력 파일명에 .md 확장자)

옵션:

  • --table-line-breaks [space|br] - 표 셀 내 줄바꿈 처리 방식 (기본값: space)
    • space - LLM 최적화: 공백으로 연결하여 깔끔한 텍스트 생성
    • br - 가독성 우선: <br> 태그로 시각적 구분

info

HWP/HWPX 파일 정보를 표시합니다.

hwp2md info INPUT_FILE

표 처리

Space 모드 (기본값, LLM 최적화)

| 2,000만원까지 3,000만원까지 5,000만원까지 | 3.79 3.07 2.14 |
  • LLM 파싱에 적합한 깔끔한 텍스트
  • 패턴 매칭 친화적
  • 토큰 수 절감

BR 모드 (가독성 우선)

| 2,000만원까지<br>3,000만원까지<br>5,000만원까지 | 3.79<br>3.07<br>2.14 |
  • Markdown 렌더러에서 시각적 구분
  • 원본 레이아웃 보존
  • 사람이 읽기에 적합

셀 병합

병합된 셀은 내용을 모든 병합 셀에 반복하는 전략을 사용합니다:

원본 표:

┌─────────────┬──────┐
│  카테고리    │  값  │
├─────────────┼──────┤
│             │ 100  │
│   병합셀    ├──────┤
│             │ 200  │
└─────────────┴──────┘

Markdown 출력:

| 카테고리 | 값  |
| 병합셀   | 100 |
| 병합셀   | 200 |

LLM이 표 의미를 이해하지 않아도 데이터를 정확히 연결할 수 있습니다.

API 문서

HWPFile

HWP 파일 읽기를 위한 컨텍스트 매니저입니다.

from hwp2md.parser import HWPFile

with HWPFile('input.hwp') as hwp:
    info = hwp.get_file_info()
    section_count = hwp.get_section_count()
    section_data = hwp.read_section(0)

메서드:

  • get_file_info() -> dict - 파일 메타데이터
  • get_section_count() -> int - 구역 수
  • read_section(index: int) -> bytes - 구역 원시 데이터

convert_hwp_to_markdown / convert_hwpx_to_markdown

HWP 또는 HWPX 파일을 Markdown 문자열로 변환합니다.

from hwp2md.converter import convert_hwp_to_markdown, convert_hwpx_to_markdown

# HWP
markdown = convert_hwp_to_markdown(hwp, table_line_break_style='space')

# HWPX
markdown = convert_hwpx_to_markdown(hwpx, table_line_break_style='space')

파라미터:

  • hwp (HWPFile) / hwpx (HWPXFile) - 열린 파일 객체
  • table_line_break_style (str) - 줄바꿈 처리: 'space' (기본값) 또는 'br'

반환값:

  • str - Markdown 형식 텍스트

HWPXFile

HWPX (ZIP+XML) 파일 읽기를 위한 컨텍스트 매니저입니다.

from hwp2md.hwpx_parser import HWPXFile

with HWPXFile('input.hwpx') as hwpx:
    info = hwpx.get_file_info()
    section_count = hwpx.get_section_count()
    section_xml = hwpx.get_section_xml(0)

메서드:

  • get_file_info() -> dict - 파일 메타데이터 (포맷, 버전, 섹션 수)
  • get_section_count() -> int - 구역 수
  • get_section_xml(index: int) -> ET.Element - 구역 XML 루트 엘리먼트
  • list_contents() -> list[str] - ZIP 내용물 목록

개발

환경 설정

# 저장소 클론
git clone https://github.com/jc-kim/hwp2md.git
cd hwp2md

# 의존성 설치 (pnpm 모노레포)
pnpm install

# JavaScript 패키지 빌드
cd packages/js
pnpm build

# Python 테스트 실행
cd packages/python
uv run pytest

프로젝트 구조 (모노레포)

hwp2md/
├── packages/
│   ├── python/                      # Python 구현체
│   │   ├── src/hwp2md/
│   │   │   ├── __init__.py
│   │   │   ├── cli.py              # CLI 인터페이스
│   │   │   ├── parser.py           # HWP 5.0 파일 파서
│   │   │   ├── hwpx_parser.py      # HWPX (ZIP+XML) 파서
│   │   │   ├── record.py           # 레코드 구조
│   │   │   ├── paragraph.py        # 문단 추출
│   │   │   ├── table.py            # 표 추출
│   │   │   └── converter.py        # Markdown 변환
│   │   └── pyproject.toml
│   │
│   └── js/                          # JavaScript/TypeScript 구현체
│       ├── src/
│       │   ├── index.ts            # 메인 내보내기
│       │   ├── parser.ts           # HWP 5.0 파일 파서
│       │   ├── hwpx_parser.ts      # HWPX (ZIP+XML) 파서
│       │   ├── record.ts           # 레코드 리더
│       │   ├── paragraph.ts        # 문단 파서
│       │   ├── table.ts            # 표 파서
│       │   ├── converter.ts        # Markdown 변환
│       │   ├── types.ts            # TypeScript 타입
│       │   ├── browser.ts          # 브라우저 진입점
│       │   ├── cli/index.ts        # CLI
│       │   └── utils/              # 유틸리티
│       ├── dist/                   # 빌드 결과물
│       └── package.json
│
├── examples/                        # 예제 HWP 파일
├── docs/                           # 문서
├── pnpm-workspace.yaml             # 모노레포 설정
├── package.json                    # 루트 package.json
└── tsconfig.base.json              # 공유 TypeScript 설정

기여하기

기여를 환영합니다! Pull Request를 자유롭게 제출해 주세요.

  1. 저장소를 포크합니다
  2. 기능 브랜치를 생성합니다 (git checkout -b feature/amazing-feature)
  3. 변경사항을 커밋합니다 (git commit -m 'Add amazing feature')
  4. 브랜치에 푸시합니다 (git push origin feature/amazing-feature)
  5. Pull Request를 생성합니다

설계 철학

HWP2MD는 LLM 가독성을 최우선 목표로 설계되었습니다:

  • 깔끔한 텍스트: 최적의 토크나이징을 위한 최소한의 포맷팅
  • 의미 구조 보존: 시각적 레이아웃보다 문서의 의미 보존
  • 패턴 친화적: 패턴 매칭과 데이터 추출에 적합한 출력
  • 정보 손실 없음: 모든 텍스트를 잘림 없이 보존

다음 용도에 적합합니다:

  • RAG (Retrieval-Augmented Generation) 파이프라인
  • 문서 분석 및 요약
  • 지식 베이스 구축
  • 텍스트 마이닝 및 NLP 작업

제한사항

  • HWP 5.0 및 HWPX 지원 - 이전 HWP 형식(HWP 3.0, HWP 97, HWP 2002 등)은 지원하지 않음
    • 레거시 HWP 파일은 한컴오피스에서 HWP 5.0 또는 HWPX로 변환 가능
    • 레거시 형식 감지 시 오류 발생
  • 텍스트 & 표 - 현재 텍스트와 표만 추출하며, 이미지 및 복잡한 개체는 건너뜀
  • 한국어 중심 - 한국어 문서에 최적화 (UTF-16LE 인코딩)
  • 기본 서식만 - 글꼴, 색상, 고급 스타일은 보존하지 않음

라이선스

MIT License - 자세한 내용은 LICENSE 파일을 참고하세요.

링크

About

HWP file to markdown converter

Resources

Readme
MIT license

Contributing

Contributing

Security policy

Security policy
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages