Hwpx Editing

HWPX Editing

HWPX is a zip of XML (HWPML). The traps that corrupt a file aren't obvious from the outside, so read the relevant section of references/hwpx-guide.md before editing, and run the scripts in scripts/ to repack and verify — don't hand-roll the zip or eyeball correctness.

> HWPX only. This handles .hwpx (zip + XML) exclusively. A legacy .hwp > (OLE binary, signature D0CF11E0) must first be converted in 한글 via > 다른 이름으로 저장 → HWPX(.hwpx). The scripts detect .hwp and say so.

The one rule that matters most

Never re-zip an HWPX with a normal zip writer. 한글 rejects a file whose unchanged entries were re-deflated. Use the raw-preserving repacker (scripts/hwpxlib.py:repack_preserve): it byte-copies every entry you didn't touch and re-deflates only what you changed, so a no-op repack is byte-identical to the source — meaning "if the original opens in 한글, your edit opens too."

Workflow

1. Inspect first. python scripts/inspect_hwpx.py FILE.hwpx --breaks — see

per-section counts (paragraphs, tables, pic, equation, fields) and, crucially, which paragraphs carry a hidden pageBreak/columnBreak. If a heading is split from its content or a page/column is blank, hunt those breaks first (§6-A) — don't reach for keepWithNext. Body-paragraph breaks are usually leftover cruft.

1. Read the matching guide section in references/hwpx-guide.md (map below).

The XML ids/refs (charPrIDRef, paraPrIDRef, borderFillIDRef, …) differ per file — always read them from the actual file, never assume.

1. Edit the XML with lxml, following the invariants:

• After editing or creating any paragraph, remove its ``

(cached line layout goes stale → broken spacing). After structural edits, strip linesegarray from the whole section so 한글 fully re-lays-out. Use hwpxlib.strip_linesegarray.

• When you clone a node (endnote, table, equation, image), it inherits the

original's id/instId → duplicates → instability. Reassign fresh ids with hwpxlib.make_uid, including nested subList>p / tbl/tc/p ids.

• Reuse existing charPr/paraPr definitions instead of adding new ones;

if you must add, update the itemCnt or 한글 rejects the file.

1. Repack with hwpxlib.repack_preserve(src, changed, out, added):

changed = edited entries (keep the XML declaration on top), added = new entries like BinData/imageN.png or a new sectionN.xml (also register these in content.hpf).

1. Verify every build: python scripts/verify.py EDITED.hwpx --orig ORIG.hwpx.

All hard checks must pass (byte-identity self-check, well-formed XML incl. content.hpf, zero duplicate ids, zip integrity + mimetype first/STORED). It also prints a minimal-change diff so you can confirm only intended changes are present.

1. Round-trip in 한글. LibreOffice can't render HWPX, so render-dependent

judgments (which heading orphans, whether spacing looks right) need the user to open the file in 한글 and, for equations/TOC, run 도구→차례 새로 고침 or double-click→close to finalize. Say so.

Scripts (scripts/) — run these, don't reinvent

| Script | Purpose | |---|---| | hwpxlib.py | Library: repack_preserve, own (real body text, excludes 각주·미주·메모 / footnote·endnote·memo), make_uid, strip_linesegarray, find_duplicate_ids, structural_counts, plus §7 verify helpers. Import it. | | inspect_hwpx.py FILE [--text] [--breaks] | Structure dump; find hidden page/column breaks. | | verify.py EDITED [--orig ORIG] | Run the full §7 checklist; non-zero exit on failure (CI-gateable). | | selftest.py | Prove the repacker is lossless without a real file. | | tables_to_xlsx.py FILE [OUT] | Export tables to Excel (.xlsx), merged cells preserved (needs openpyxl). Cells with only an image/equation → [그림]/[수식]; legacy .hwp is refused with guidance. | | hwpx_to_markdown.py FILE [OUT.md] | Extract the document's text + tables as Markdown (for an LLM to read/summarize; no OUT → stdout). | | hwpx_to_docx.py FILE [OUT.docx] | Export to Word (.docx), tables + merged cells preserved (needs python-docx; for journals / non-한글 co-authors). | | data_to_hwpx_table.py DATA.(xlsx\|csv) TARGET.hwpx [OUT] [--sheet] | Insert an Excel/CSV table into a 한글 doc, merged cells preserved (needs openpyxl for xlsx; TARGET must contain a table for cell styling; CSV encoding auto). |

Scripts need lxml (pip install lxml); the table→Excel export also needs openpyxl. Python 3.10+.

Where to read in the guide (references/hwpx-guide.md)

Load only the section you need — the guide opens with a "흔한 실패 TOP" (top failure modes); skim that first, then jump to:

• §1 Structure & parsing — namespaces, own(), "check all sections", table

text per-cell (not bulk itertext).

• §2 Repack (raw-preserving) — the crown-jewel repacker. Mirrors hwpxlib.
• §3 Common rules — linesegarray removal, id-dedup after cloning.
• §4 Content editing — paragraphs, tables (cell width sums must equal table

width or 한글 rejects it; merges), images (orgSz=px×75, size math, verify by content not extraction order, matplotlib legibility "small figure, big text"), formatting, endnotes/footnotes (`` wrapping required), memos, and typo-audit scoping (no blanket regex).

• §5 Columns · TOC · equations — colPr, TABLEOFCONTENTS from outline-level

paragraphs, 한컴 equation script (not LaTeX; table of forms).

• §6 Page/column management — hidden breaks first, orphaned-heading

prevention (keepWithNext, no empty paragraph after a heading, conditional columnBreak), blank-page cleanup, wide tables → 1-column region + moving a secPr block across section boundaries.

• §7 Verification checklist — what verify.py automates, plus the round-trip

caveat.

Guardrails

• This edits documents only; it never needs the user's credentials, and it doesn't

fetch or execute remote content. Work on a copy and keep the original.

• Preserve the author's content: only change what the user asked for; the

minimal-change diff in verify.py is your proof.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kangdacool
• Source: kangdacool/hwpx-editing-skill
• License: MIT

Install and usage instructions live in the source repository linked above.