hwp2md

Node.js 및 브라우저용 HWP/HWPX to Markdown 변환기.

한글(HWP 5.0 및 HWPX) 파일을 LLM에 최적화된 깔끔한 Markdown으로 변환합니다.

주요 기능

• ✅ HWP 5.0 및 HWPX 파일에서 텍스트 추출
• ✅ HWPX (ZIP+XML) 형식 지원 (확장자 자동 감지)
• ✅ 표를 Markdown 형식으로 변환
• ✅ 문서 구조 보존
• ✅ 셀 병합 처리 (LLM 최적화를 위한 내용 반복)
• ✅ Node.js 및 브라우저 환경 지원
• ✅ TypeScript 타입 정의 포함

설치

npm install hwp2md
# 또는
pnpm add hwp2md
# 또는
yarn add hwp2md

사용법

Node.js

import { convert } from "hwp2md";

// HWP 또는 HWPX 변환 (확장자로 자동 감지)
const markdown = await convert("document.hwp");
const markdown2 = await convert("document.hwpx");
console.log(markdown);

// 옵션 지정
const markdown3 = await convert("document.hwp", {
  tableLineBreakStyle: "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

# 전역 설치
npm install -g hwp2md

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

# Markdown으로 변환
hwp2md convert document.hwp output.md

# HWPX 파일 변환 (자동 감지)
hwp2md convert document.hwpx output.md

# 옵션 지정
hwp2md convert document.hwp output.md --table-line-breaks br

API

convert(input, options?)

HWP/HWPX 파일을 Markdown으로 변환합니다 (확장자로 자동 감지).

파라미터:

• input: 파일 경로 (Node.js, .hwp 또는 .hwpx), ArrayBuffer, 또는 Uint8Array
• options: 변환 옵션
  • tableLineBreakStyle: 'space' (기본값) 또는 'br'

반환값: Promise<string> - Markdown 내용

convertFromFile(file, options?) (브라우저 전용)

브라우저 File 객체에서 HWP를 변환합니다.

파라미터:

• file: input 엘리먼트의 File 객체
• options: 변환 옵션

반환값: Promise<string> - Markdown 내용

HWPFile

HWP 파일 파싱을 위한 저수준 API입니다.

import { HWPFile } from "hwp2md";

const hwp = await HWPFile.fromFile("document.hwp");
hwp.open();

console.log(hwp.fileHeader);
console.log(hwp.getSectionCount());

const sectionData = hwp.readSection(0);
hwp.close();

HWPXFile

HWPX 파일 파싱을 위한 저수준 API입니다.

import { HWPXFile, convertHwpxToMarkdown } from "hwp2md";

const hwpx = await HWPXFile.fromFile("document.hwpx");
hwpx.open();

console.log(hwpx.getSectionCount());
const markdown = convertHwpxToMarkdown(hwpx);

hwpx.close();

옵션

tableLineBreakStyle

표 셀 내 줄바꿈 처리 방식:

• 'space' (기본값): 공백으로 연결 - LLM 처리에 최적화
• 'br': <br> 태그 사용 - 가독성 우선

제한사항

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

개발

# 의존성 설치
pnpm install

# 빌드
pnpm build

# 테스트
pnpm test

# 타입 체크
pnpm typecheck

라이선스

MIT