kordoc

모두 파싱해버리겠다 — Parse them all.

Korea's document hell is second to none. Built by a civil servant who survived seven years in it.

Convert HWP 3.x/5.x, HWPX, HWPML, PDF, XLS/XLSX, DOCX, PPTX and PNG/JPG/WebP to Markdown and structured data. Use it as a library, CLI or MCP server.

한국어 · Usage guide · Benchmarks · Changelog

• 📊 0.963 overall on the public PDF benchmark — opendataloader-bench, 200 documents. Ranked first against 12 published parsers in the 2026-09-29 comparison. Measurement details
• 🇰🇷 100% Korean document table structure match — all 10,461 visible tables from 2,429 original HWPX documents. 4.22.0 verification

If this saves you time, a GitHub ⭐ helps others find it.

_{▶ Click to play on YouTube. Narration is in Korean.}

New video: kordoc 공개벤치 1위 마크 — public benchmark · 2026-09-27 · 1 min 31 sec · Korean

Install

Node.js 20+ · macOS / Linux / Windows

npm install kordoc

Run the CLI without installing it globally: npx kordoc. PDF/OCR dependencies are installed by default; omitting them with --omit=optional limits those features.

Connect an AI agent

npx -y kordoc setup

Registers MCP with installed clients such as Claude Desktop, Claude Code, Cursor and Codex. Restart the client to use 17 tools for parsing, comparison, generation, rendering and more.

Claude Code plugin:

/plugin marketplace add chrisryugj/kordoc
/plugin install kordoc@kordoc

Manual MCP setup and installation troubleshooting

Quick start

CLI

npx kordoc document.hwpx -o document.md
npx kordoc *.pdf --jobs 4 -d ./output
npx kordoc document.pdf --format json --pages 1-3
npx kordoc scan.pdf --ocr -o scan.md
npx kordoc generate report.md --preset report -o report.hwpx
npx kordoc fill --template gian -j values.json -o draft.hwpx

--jobs converts files in parallel and increases memory use. Batch conversion details

For the report, plan, gaejosik and bangchim presets, a blockquote right after the # title (> …하고자 함) becomes the summary box (gaejosik puts it under the title box on the first body page when the cover is on, the default; with cover: false the first # is a chapter header and the quote stays a ※ note). Keep it to one sentence (commas allowed) within three lines; longer or multi-sentence summaries produce a warning. For ministry, > ▪ … blockquotes become performance summary boxes wherever they appear.

JavaScript / TypeScript

import { parse, markdownToHwpx } from "kordoc"
import { writeFile } from "node:fs/promises"

const result = await parse("document.hwpx")
if (result.success) {
  console.log(result.markdown)
  // result.blocks: structured data; result.metadata: document metadata
}

const hwpx = await markdownToHwpx("# Plan\n\nBody text", {
  gongmun: { preset: "report" },
})
await writeFile("report.hwpx", Buffer.from(hwpx))

Parse options, APIs, forms and rendering examples

Features

Extract Markdown for format-preserving patches with --keep-layout-tables. Unsupported edits are skipped with a reason. Full CLI and API reference

Validation

4.22.5 verification · 2026-10-17. Results use fixed corpora and reference criteria.

Table structure, cell content and visual fidelity are separate metrics. The nested-table 100% applies only to these 101 tables, not all PDF parsing or page layout. See benchmark details for scope, exclusions and the per-document comparison of every bench.

4.22.5 improvement verification (2026-10-17): ten alternating rounds increased exact line starts from 25,326 to 25,332/25,581 paragraphs, PDF exact table-cell content 0.990311→0.990677, and character recall 0.99865→0.99872. Fixes cover zero-width tabs, symbol advances, bullet reservations, line heights and split tables, plus PDF continuations, section headings and missing glyphs. Statute-annex cell F1 improved 0.99739→0.99778; exact structure remains 342/346. Additional five rounds, cross-effects and upstream review (Korean) · Earlier five rounds (Korean)

Merged corner cells are retained within the existing logical grid during empty-row folding. Six number glyphs in the reproduced PDF are now restored; HTML rule rendering and unregistered font glyphs remain documented limitations (Korean).

The external opendataloader-bench, 200 documents was verified on the same corpus with the 4.22.5 release candidate: overall 0.963 with defaults, 0.939 with OCR off. Options and reproduction

Recent updates

Latest release: 4.22.5 · 2026-10-17

Use --ocr --ocr-lines --format json to export OCR line boxes and confidence. Select the detector and resolution with --ocr-det and --ocr-det-long-side. OCR lines and models

See the changelog for details on every release.

FAQ

How do I convert an HWP or HWPX file to Markdown?
npx kordoc document.hwp -o document.md. It reads the file directly, without Hancom Office. Convert many files at once with npx kordoc *.hwpx -d ./output.

How do I let Claude, Cursor or another AI agent read Korean documents?
Run npx -y kordoc setup to register the MCP server. The agent can then read, compare and fill HWP, PDF and Excel files from a file path.

Does it work on an air-gapped network?
Yes. KORDOC_OFFLINE=1 blocks all outbound traffic, and OCR runs on the local CPU with no API key. Offline deployment

Can I use it for RAG indexing?
--format chunks emits structure chunks with heading breadcrumbs plus standalone table chunks. Use --table-format gfm (API: tableFormat: "gfm") for tables without HTML. From Python or Java, use the Python SDK or Java SDK.

Documentation and security

• Usage guide: complete CLI, MCP tools, APIs and format support
• Java SDK · Python SDK: parse from Java and Python systems through a resident engine worker (worker protocol, Korean)
• Government-document generation · Architecture
• Offline deployment: KORDOC_OFFLINE=1; MCP file scope with KORDOC_ROOT
• Security policy · MIT license · Third-party notices

About the Author

A local civil servant in Korea. Built this after seven years of wrestling HWP files at the Gwangjin-gu District Office in Seoul. Validated on thousands of real government documents across five public-sector projects.