toMarkdown

HWP 문서를 마크다운 형식으로 변환하는 함수입니다.

예제

Web

React Native

Node.js

import { toMarkdown } from '@ohah/hwpjs';

// 파일 입력에서 HWP 파일 읽기
const fileInput = document.querySelector('input[type="file"]');
fileInput.addEventListener('change', async (e) => {
  const file = (e.target as HTMLInputElement).files?.[0];
  if (!file) return;

  try {
    const arrayBuffer = await file.arrayBuffer();
    const data = new Uint8Array(arrayBuffer);

    // 마크다운으로 변환
    const result = toMarkdown(data, {
      image: 'base64',
      useHtml: true,
      includeVersion: true,
      includePageInfo: false,
    });
    console.log(result.markdown);
  } catch (error) {
    console.error('변환 실패:', error);
  }
});

import { Hwpjs } from '@ohah/hwpjs';
import RNFS from 'react-native-fs';
import { Platform } from 'react-native';

try {
  // 파일 경로 설정
  const filePath = Platform.OS === 'ios'
    ? `${RNFS.MainBundlePath}/document.hwp`
    : `${RNFS.DocumentDirectoryPath}/document.hwp`;

  // 파일을 base64로 읽기
  const fileData = await RNFS.readFile(filePath, 'base64');

  // base64를 ArrayBuffer로 변환
  const binaryString = atob(fileData);
  const length = binaryString.length;
  const bytes = new Uint8Array(length);
  for (let i = 0; i < length; i++) {
    bytes[i] = binaryString.charCodeAt(i);
  }

  // 마크다운으로 변환 (ArrayBuffer 직접 사용)
  const result = Hwpjs.toMarkdown(bytes.buffer, {
    image: 'base64',
    useHtml: false,
    includeVersion: false,
    includePageInfo: false,
  });
  console.log(result.markdown);
} catch (error) {
  console.error('변환 실패:', error);
}

import { readFileSync } from 'fs';
import { toMarkdown } from '@ohah/hwpjs';

try {
  // HWP 파일 읽기
  const fileBuffer = readFileSync('./document.hwp');

  // 마크다운으로 변환
  const result = toMarkdown(fileBuffer, {
    image: 'base64', // 또는 'blob'으로 별도 이미지 배열 받기
    useHtml: false,
    includeVersion: false,
    includePageInfo: false,
  });

  console.log(result.markdown);
  // base64 옵션 사용 시: result.images는 빈 배열
  // blob 옵션 사용 시: result.images에 ImageData 배열 포함
} catch (error) {
  console.error('변환 실패:', error);
}

시그니처

function toMarkdown(data: Buffer, options?: ToMarkdownOptions): ToMarkdownResult

매개변수

`data: Buffer`

변환할 HWP 파일의 바이트 배열입니다 (Buffer 또는 Uint8Array).

예제:

import { readFileSync } from 'fs';
const fileBuffer = readFileSync('./document.hwp');
const data = new Uint8Array(fileBuffer);

`options?: ToMarkdownOptions`

마크다운 변환 옵션입니다 (선택 사항).

interface ToMarkdownOptions {
  /** 이미지 형식: 'base64'는 마크다운에 base64 데이터 URI를 직접 포함, 'blob'은 별도 ImageData 배열로 반환 (기본값: 'blob') */
  image?: 'base64' | 'blob';
  /** HTML 태그 사용 여부 (true인 경우 테이블 등 개행 불가 영역에 <br> 태그 사용) */
  useHtml?: boolean;
  /** 버전 정보 포함 여부 */
  includeVersion?: boolean;
  /** 페이지 정보 포함 여부 */
  includePageInfo?: boolean;
  /** 이미지를 파일로 저장할 디렉토리 경로 (선택) */
  imageOutputDir?: string;
}

반환값

`ToMarkdownResult`

변환된 마크다운 문자열과 이미지 데이터를 포함하는 객체입니다.

Web/Node.js:

interface ToMarkdownResult {
  /** 이미지 참조가 포함된 마크다운 문자열 */
  markdown: string;
  /** 추출된 이미지 데이터 (image: 'blob' 옵션 사용 시) */
  images: ImageData[];
}

interface ImageData {
  /** 이미지 ID (예: "image-0") */
  id: string;
  /** 이미지 데이터 (Uint8Array) */
  data: Buffer;
  /** 이미지 형식 (예: "jpg", "png", "bmp") */
  format: string;
}

React Native:

interface ToMarkdownResult {
  /** 이미지 참조가 포함된 마크다운 문자열 */
  markdown: string;
  // 주의: React Native에서는 images 필드가 지원되지 않습니다.
  // 이미지는 base64 데이터 URI로 마크다운에 직접 포함됩니다.
}

:::warning 플랫폼별 차이점:

Web/Node.js: image: 'blob' 옵션 사용 시 images 배열에 ImageData 객체가 포함됩니다.
React Native: images 필드가 지원되지 않으며, 이미지는 항상 base64 데이터 URI로 마크다운에 직접 포함됩니다. :::

다음 내용이 포함됩니다:

문서 제목 및 버전 정보 (옵션에 따라)
본문 텍스트
표 (Table) - 마크다운 테이블 형식으로 변환
이미지 - base64 데이터 URI 또는 별도 이미지 배열
컨트롤 객체 (글상자 등)
페이지 구분선 (페이지 나누기 시, 옵션에 따라)

지원 기능

텍스트 추출

문단 텍스트 추출
제어 문자 제거
공백 정규화

컨트롤 객체

다음 컨트롤 객체가 감지되고 마크다운으로 변환됩니다:

표 (Table): 마크다운 테이블 형식으로 변환
이미지: base64 데이터 URI 또는 별도 이미지 배열로 제공
그리기 개체 (Shape Object): 글상자 등
머리말/꼬리말 (Header/Footer): *[머리말]*, *[꼬리말]*
단 정의 (Column Definition): *[단 정의]*

출력 형식

# HWP 문서

본문 내용이 여기에 표시됩니다.

| 열1 | 열2 | 열3 |
|-----|-----|-----|
| 셀1 | 셀2 | 셀3 |
| 셀4 | 셀5 | 셀6 |

![이미지](data:image/jpeg;base64,/9j/4AAQSkZJRg...)

또는 이미지를 별도로 받은 경우:

![이미지](image-0)

---

[다음 페이지 내용...]

옵션에 따른 출력 차이

includeVersion: true: 문서 버전 정보가 포함됩니다.
includePageInfo: true: 페이지 구분선이 포함됩니다.
useHtml: true: 테이블 등 개행 불가 영역에 <br> 태그가 사용됩니다.
image: 'base64': 이미지가 마크다운에 base64 데이터 URI로 직접 포함됩니다.
image: 'blob': 이미지가 별도 배열로 반환되고, 마크다운에는 참조만 포함됩니다.

에러

HWP 파일 형식이 올바르지 않거나 변환에 실패한 경우 에러가 발생합니다.

HWP 파일 형식이 올바르지 않은 경우
파일이 손상된 경우
마크다운 변환에 실패한 경우

제한사항

그리기 개체: 일부 그리기 개체의 실제 내용은 추출되지 않을 수 있습니다.
스타일링: 글자 모양, 문단 모양 등의 서식 정보는 반영되지 않습니다.
복잡한 레이아웃: 일부 복잡한 레이아웃은 완벽하게 변환되지 않을 수 있습니다.

참고

이 함수는 Rust로 구현된 hwp-core 라이브러리를 사용하여 HWP 파일을 파싱하고 마크다운으로 변환합니다.
표 내용은 마크다운 테이블 형식으로 변환됩니다.
이미지는 base64 데이터 URI로 임베드하거나 별도 배열로 받을 수 있습니다.
HTML 형식으로의 변환은 toHtml 함수를 참고하세요.

#toMarkdown

#예제

#시그니처

#매개변수

#data: Buffer

#options?: ToMarkdownOptions

#반환값

#ToMarkdownResult

#지원 기능

#텍스트 추출

#컨트롤 객체

#출력 형식

#옵션에 따른 출력 차이

#에러

#제한사항

#참고