kordoc: A TypeScript Toolkit for Turning Korean Government Documents into Markdown and Back

The Problem: Korean Document Formats Are a Wall for Automation

Korean public offices generate documents in HWP and HWPX, proprietary formats that standard parsers ignore. PDFs from these tools often carry rasterized tables or missing text layers. The author, a former civil servant, built kordoc to turn this pile into Markdown that an LLM can read, analyze, and regenerate. The target user is an AI agent or a developer who needs to automate workflows like reading a notice, filling a form, or comparing two versions of a regulation. The README lists support for HWP 3.x/5.x, HWPX, HWPML, PDF, XLS, XLSX, DOCX, and images (PNG/JPG/WebP) with automatic OCR. This is not a general-purpose document converter; it is aimed squarely at the Korean public-sector document lifecycle.

How It Works: Parsing, Patching, and Rendering with Format Preservation

The core operation is converting any supported file to Markdown. But kordoc goes further. It can take that Markdown, let you edit it, and then patch the original HWPX or HWP binary, replacing only the changed paragraph or table cell text while leaving the original formatting untouched. The README claims this is lossless, down to the byte. For tables, v3.7 added row insertion and deletion that inherits original formatting, and v3.8 added filling empty cells in HWP 5.x. There is also a render pipeline that reproduces the original layout as SVG using Hancom's stored layout cache (linesegarray for HWPX, PARA_LINE_SEG for HWP5). For files without that cache, like AI-generated HWPX, a pure TypeScript reflow engine does the layout. The v4.7.3 release notes describe how page boundaries are now restored from the actual layout cache, giving real page numbers instead of section approximations, with a pageMode metadata field to distinguish layout versus section mode.

Getting Started: npx Setup and the MCP Server

Installation is a single command: npx -y kordoc setup. This runs an interactive wizard that detects installed AI clients (Claude Desktop, Cursor, Claude Code, Windsurf, VS Code, Gemini CLI, Zed, Antigravity, Codex) and patches their config files automatically. On Windows, it wraps npx with cmd /c to avoid PowerShell execution policy issues. After restarting the client, 15 document tools become available, including parse_document, parse_table, fill_form, patch_document, and generate_document. For CLI-only use, you can skip setup and run npx kordoc <file> directly. There is also a Claude Code plugin installation path: /plugin marketplace add chrisryugj/kordoc, then /plugin install kordoc@kordoc, which activates a skill when .hwp or .hwpx files are mentioned. The README includes troubleshooting for a broken global install, advising npm uninstall -g kordoc followed by npx -y kordoc@latest setup.

Form Filling, Seals, and Charts: Beyond Text Extraction

Beyond parsing, kordoc automates document creation tasks. The fill_form tool inserts values into template blanks while preserving original fonts, sizes, and alignment. The kordoc seal command places a stamp PNG in front of anchor text like '(인)' or '서명 또는 인', using floating positioning so the table or page does not shift. There is a chart generator that turns a Markdown code fence with type/cat/series lines into native Hancom charts (OOXML chartSpace), supporting 20 types including bar, line, pie, and scatter. The v4.0 release added a government document engine that decodes 16 official form types and 60 real approval drafts, with features like automatic '끝.' in drafts, 8-level bullet numbering, and a lint command (kordoc lint) that checks 13 rules of official document notation. These features suggest the project is not just a converter but a full document automation suite for Korean administrative writing.

OCR and RAG Support: Handling Scans and Structuring Output

Version 4.2 added built-in OCR using PP-OCRv5 Korean, running locally on CPU with no API key or external service. The parser can detect raster lines in scanned documents and restore tables from images. For RAG use, v4.1 to v4.8 introduced structured chunking with breadcrumbs that preserve heading and bullet hierarchy. The parse output includes a JSON structure with markdown, pages, blocks, and metadata. The README shows an example where the markdown field contains the full document, pages contain per-page markdown, and blocks hold individual elements. One limitation is documented: a table that spans multiple pages is treated as a single block starting on the first page, so the markdown for intermediate pages is empty, though the array length equals the page count. This is a real constraint for anyone building a page-based RAG pipeline.

Known Limitations and Failure Modes

The README is candid about several weak spots. For seal placement, nested tables, text boxes, and tab/line-break paragraphs are only approximate, and the tool emits warnings; you must verify in Hancom and adjust with --dx/--dy flags. The v3.16.1 patch notes mention fixing 55 defects in a category called 'quietly wrong output after success message', which is a class of failure where the tool reports success but produces incorrect results. The v3.16.2 patch fixed a PDF parser bug that mistook '<신 설>' labels in a comparison table for text boxes and broke the entire table into paragraphs. Page boundaries for files without layout cache fall back to section approximation, and using the pages filter in that mode triggers a PAGE_BOUNDARY_APPROXIMATE warning. These are not hypothetical issues; they are documented in release notes, so you should test your specific document types before trusting the output blindly.

Alternative Approaches and Trade-offs

The main alternative is to use Hancom's own COM automation on Windows, which the README mentions as a verification method ('한글 COM 실렌더로 조판까지 실측 검증'). That approach gives exact fidelity but requires a Windows machine with Hancom installed, making it unsuitable for server-side or cross-platform workflows. kordoc's pure TypeScript reflow engine and local OCR avoid that dependency, but they introduce approximation risks. Another alternative is to convert HWP to PDF first and then use a generic PDF-to-Markdown tool, but that loses table structure and the ability to patch back to the original format. kordoc's key differentiator is the round-trip capability: you can edit Markdown and write back to HWPX or HWP without touching the original formatting. No generic converter offers that. The trade-off is complexity: the patch mechanism, the layout cache parsing, and the OCR all add moving parts that can fail on edge cases.

Maintenance and License Considerations

The project is actively maintained, with releases on a weekly or biweekly basis; the latest v4.10.0 is dated 2026-08-27, just days before the last push. The release notes show a pattern of rapid bug fixes and feature additions, which is good for responsiveness but also means the API may shift. The README references version-specific behaviors, so you should pin a version if you rely on a particular feature. The license is MIT, which permits commercial use, modification, and redistribution without copyleft obligations. However, the project uses PP-OCRv5, which may have its own license; the README does not clarify that, so verify the OCR model's terms if you distribute the tool. The npm package is the distribution channel, and the setup wizard handles client config patching, which means upgrading kordoc might require re-running setup if the config format changes. There is no mention of a migration guide, so budget time for testing after each major version bump.

Editorial conclusion

Adopt kordoc if you regularly process Korean government or office documents and need a local, scriptable pipeline that preserves table structure and original formatting. Skip it if your work is mostly English PDFs or if you need a stable GUI; the CLI and MCP focus assumes comfort with Node.js and command-line workflows. Before committing, verify that your specific HWP version (3.x vs 5.x) and PDF quirks (e.g., scanned tables) are handled by running kordoc on a sample set, and check the patchHwp soft-wrap integrity notes for row edits. Also confirm the Node.js 18+ requirement and the MIT license fit your distribution model.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes