Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

HwpForge

한글 문서(HWP/HWPX)를 프로그래밍으로 제어하는 Rust 라이브러리

crates.io docs.rs License: MIT OR Apache-2.0

본 제품은 한컴의 HWP 문서 파일(.hwp) 공개 문서를 참고하여 개발하였습니다.


HwpForge란?

HwpForge는 한컴 한글의 HWP/HWPX 문서를 Rust로 읽고, 쓰고, 변환할 수 있는 라이브러리입니다. CLI·Python의 지원 읽기·편집 연산은 HWP5 입력을 자동 변환하며 편집 결과는 HWPX입니다. .hwp 저장은 지원하지 않습니다. 변환 손실의 거부·허용과 대상 명령은 CLI 입력 정책을 참고합니다. Rust의 hwpforge::ops와 MCP에는 명시적으로 변환한 HWPX를 전달합니다.

주요 기능

  • HWPX 풀 코덱 — HWPX 파일 디코딩/인코딩 + 무손실 라운드트립
  • HWP5 입력과 HWPX 출력 — CLI·Python의 지원 읽기·편집 자동 변환과 명시적 변환·점검 경로를 제공합니다
  • Markdown 브릿지 — GFM Markdown ↔ HWPX 변환
  • PDF 내보내기 — 문서에 들어 있는 조판 캐시(layout cache)를 재생해 PDF로 렌더 (to-pdf)
  • 편집 연산 (ops) — 누름틀 채우기, 표 셀 편집, 문단 삽입·삭제, 템플릿 스탬핑, diff·검증을 CLI·MCP·Python이 같은 구현으로 공유
  • Python 바인딩 — pip install hwpforge
  • MCP 서버 — AI 도구에서 한글 문서를 직접 생성·편집 (MCP 레퍼런스)
  • YAML 스타일 템플릿 — 재사용 가능한 디자인 토큰 (Figma 패턴)
  • 타입 안전 API — 브랜드 인덱스, 타입스테이트 검증, unsafe 코드 0

지원 콘텐츠

카테고리요소
텍스트런, 문자 모양, 문단 모양, 스타일 (한컴 기본 스타일 18/22/23개, 스타일 세트별)
구조표 (중첩), 이미지, 글상자, 캡션
레이아웃다단, 페이지 설정, 가로/세로, 여백, 마스터페이지
머리글/바닥글머리글, 바닥글, 쪽번호 (autoNum)
주석각주, 미주
도형선, 사각형, 타원, 다각형, 호, 곡선, 연결선, 묶음 객체, 글맵시 (채움/회전/화살표)
글자 효과덧말, 글자겹침
수식HancomEQN 스크립트
차트18종 차트 (OOXML 호환)
참조책갈피, 상호참조, 필드, 메모, 찾아보기
MarkdownGFM 디코드, 손실/무손실 인코드, YAML 프론트매터

누구를 위한 라이브러리인가?

  • LLM/AI 에이전트 — 자연어로 한글 문서 자동 생성
  • 백엔드 개발자 — 서버에서 한글 문서 프로그래밍 생성
  • 자동화 도구 — CI/CD 파이프라인에서 보고서 자동 생성
  • 데이터 파이프라인 — HWPX 문서에서 텍스트/표 추출

빠른 맛보기

#![allow(unused)]
fn main() {
use hwpforge::core::{Document, Draft, Paragraph, Run, Section, PageSettings};
use hwpforge::foundation::{CharShapeIndex, ParaShapeIndex};
use hwpforge::hwpx::{HwpxEncoder, HwpxStyleStore};
use hwpforge::core::ImageStore;

// 1. 문서 생성
let mut doc = Document::<Draft>::new();
doc.add_section(Section::with_paragraphs(
    vec![Paragraph::with_runs(
        vec![Run::text("안녕하세요, HwpForge!", CharShapeIndex::new(0))],
        ParaShapeIndex::new(0),
    )],
    PageSettings::a4(),
));

// 2. 검증 + 인코딩
let validated = doc.validate().unwrap();
let style_store = HwpxStyleStore::with_default_fonts("함초롬바탕");
let image_store = ImageStore::new();
let bytes = HwpxEncoder::encode(&validated, &style_store, &image_store).unwrap();

// 3. 파일 저장
std::fs::write("output.hwpx", &bytes).unwrap();
}

다음 단계

by Ai-Scream