gongnyang/bookforge: a Korean ebook PDF pipeline as an agent skill for Claude Code and Codex

The gap bookforge targets: markdown in, bound-book structure out

Most text-to-PDF tooling stops at typesetting a document. bookforge aims at the anatomy of a trade paperback instead: cover, a table of contents with leader dots, chapter dividers, running heads, a colophon. The README states the division of labour plainly: content is written in markdown only, layout belongs to six style packs and scripts, and quality is enforced by QC gates. The claim that matters is the last one. A PDF that fails a gate cannot exist in final/. That is a structural promise, not a stylistic preference, and it is the reason to look at this project rather than at a general-purpose converter.

The intended user is narrow. You are writing Korean, you are already inside Claude Code or OpenAI Codex, and you want a deliverable that reads like a published book rather than a formatted report. The skill is invoked from the agent, not from a web interface. Nothing in the repository suggests a hosted service, and the homepage field is empty.

What the gates actually check, and why that is a different thing from spellchecking

The gate numbers are the most concrete part of the README. G16 validates a style pack's colour and numeric contract before rendering, so a theme whose real output disagrees with its declaration is caught ahead of the build. G1-SCALE compares absolute type sizes to block a document that has quietly shrunk throughout. G17 re-checks diagram placement on the final page, including whether a figure splits a page or overruns the print area. G0 validates diagram sources before render; G13 checks that label text really exists in the produced PDF. G14 scans table of contents and design consistency on five axes: printed page numbers against actual folios, TOC hue family against chapter dividers, WCAG contrast floor for coloured text, section-row page numbers against real section starts, and figure or table list numbers against real caption pages.

That list is a statement about what kind of tool this is. The gates police geometry, colour, scale and pagination. They do not judge whether your argument is sound. A book can pass every gate and still be badly written, and the README does not pretend otherwise.

Two diagram tracks: AntV declarations and hand-authored SVG

Diagrams are declared as sidecar files and the build normalises and validates them before placing vector output. The first track covers ordered, comparative, hierarchical and trend visuals, declared in diagrams/fig-NN.json using the AntV Infographic DSL. Rendering happens through a vendored bundle committed to the repository, vendor/antv-ssr.bundle.mjs, pinned to @antv/infographic 0.2.19. The README describes a specific failure this avoids: the original output's foreignObject text is converted to native text elements, because Typst via usvg would otherwise drop the text silently.

The second track exists because the AntV catalogue does not cover everything. Eleven families of technical diagram, including sequence, state machine, ER, swimlane, Gantt, radar, Venn, scatter, org chart, loop and permission matrix, are drawn by the agent as SVG. Placing diagrams/fig-NN.svg next to a sidecar of {"kind":"authored"} makes the build bake fonts, force the palette, check for label collisions and enforce an 8pt floor before writing assets/fig-NN.svg.

Colour and size are contract-bound. Each palette colour declares a role (label, fill, stroke), so using a label colour as a fill is a violation the gate catches. Label size cannot exceed diagram.labelBand.maxRatio relative to body text. Height is also contractual: a diagram over diagram.maxHeightMm is pre-scaled or rejected at render time (figFitReport), and the README notes that bypassing this is still caught in the final PDF by G17-FIGFIT.

The table of contents is a declared grammar, not a template you edit

Six layout names live in a single catalogue, TOC_LAYOUTS, each registered with its level count, leader-dot presence and size ceiling measured from real books. A style pack selects one by name through toc_layout in tokens.json, and G16-SYNC catches a pack whose actual theme disagrees with that declaration before the build runs. hanging-two-level, used by insight, gives chapter rows with indented section rows and paginates across multiple spreads when it overflows, using a two-pass page-number marker. spread-single-level fixes one spread and halts the build on overflow. display-numeral puts a large chapter number column on the left. twocol-balanced adds a header band, chapter ordinal chips and dotted leaders, splitting into two balanced columns on overflow. academic-flow uses a number column, title and outer page number. flush-single-level forbids leader dots entirely.

An alternative overlay can be switched on per book. Declaring toc_layout in book.json makes magazine set as display-numeral, and the alternative layout's single-page capacity is held by a separate measured contract, toc_capacity_alt. Multi-spread styles can opt into a separate figure and table list via toc_lists, and the gate checks those page numbers too. The design choice here is deliberate: you do not restyle the contents page, you pick from measured grammars. If none of the six matches the book you have in mind, the project does not offer a path.

Installing bookforge and running a first build

The README gives a clone followed by symlinks into the three skill directories, noting that both Claude Code and Codex support symlinked skills. Run this from a shell:

git clone https://github.com/gongnyang/bookforge.git
cd bookforge
ln -sfn "$PWD" ~/.claude/skills/bookforge
ln -sfn "$PWD" ~/.codex/skills/bookforge
ln -sfn "$PWD" ~/.agents/skills/bookforge

After that, the agent should see bookforge as an available skill. The README states the skill self-checks its requirements before running. Those requirements are Typst 0.14+ for the practical, academic, essay and business styles; Python 3 with PyMuPDF and markdown-it-py for conversion and the QC gates; and a global Playwright Chromium for insight, magazine, and any book that uses diagrams, since diagram prerender runs even for Typst styles. The Python dependencies install with:

pip install pymupdf markdown-it-py

The diagram prerender dependencies are declared separately in package.json, which is private and named bookforge-diagrams. It pins @antv/infographic to 0.2.19, pixelmatch to 6.0.0 and pngjs to 7.0.0, and its description notes that Playwright resolves from the global npm root, the same way print_pdf.mjs does. The README does not document a single end-to-end command for producing a book; the workflow runs through the skill inside the agent, with style selection driven by tokens.json and per-book settings in book.json. If you want to see the target before writing anything, the nine example PDFs under examples/ are the honest starting point.

Where the pipeline is likely to stop you

The dependency surface is the first real cost. Four of the six styles need Typst 0.14 or newer. Two need a global Playwright Chromium install. Diagrams need that Chromium regardless of style, because prerender runs before Typst. That is three separate toolchains to keep aligned, and the README's own phrasing, that the skill self-checks before running, implies a failure at that check is how you find out something is missing.

Style packs are contracts, not starting points. The README says a value outside the cover_variant catalogue fails immediately rather than falling back silently. That is a defensible choice for reproducibility and an annoying one when you want a small deviation. The same holds for the palette roles and the diagram label ceiling: the system will reject a label colour used as a fill rather than render something slightly wrong.

The gates also have a defined blind spot. They verify that a diagram does not split a page, that label text exists in the PDF, that page numbers match real folios, that contrast clears a WCAG floor. None of that touches whether the diagram explains anything, or whether a chapter is worth its pages. If your problem is content quality rather than production quality, this project addresses a different problem. And the language target is Korean throughout; the README points to README.en.md for English readers, but the style rulebooks and typographic decisions are built around Korean typesetting.

How it differs from Pandoc plus a LaTeX template

The obvious alternative is Pandoc driving a LaTeX or Typst template. The difference is where the rules live. In a Pandoc setup, pagination, figure placement and table of contents behaviour are conventions you maintain in a template, and nothing verifies that the output followed them. In bookforge, pagination is a separate measured rulebook, references/pagination.md, and the density gate catches both unexplained whitespace and forced filling numerically. The README describes the pagination document as based on measurements from commercial trade books, which is a different provenance from a template someone tuned by eye.

The second difference is the regression suite. The README describes tests/mutations/ as a mutation suite that injects deliberate defects into a book and checks whether the gates catch them, across 25 judgement axes including an unmutated control group M0. That is an attempt to prove the gates work rather than assert it. A Pandoc template has no equivalent, and adding one would mean building the same apparatus. If you only need a clean PDF from markdown and you are not chasing book-grade structure, Pandoc is less machinery for the same visible result.

Licence, maintenance and what a version bump costs

The repository's licence field is NOASSERTION, which means the licence could not be classified automatically. The LICENSE file exists at the top level, so the terms are stated there and should be read directly rather than inferred from the GitHub label. One dependency note is worth flagging: the README says the diagram authoring contract absorbs the specification of cathrynlavery/diagram-design, which is MIT, re-described for Korean typesetting, palette tokens and the gate system. That is a provenance statement, not a legal conclusion, and anyone redistributing the diagram contract should check the LICENSE file themselves.

On maintenance, the last push was on 2026-09-01, and the most recent release is v2.0.0 from 2026-08-15, titled with the note that diagrams take the lead. The README distinguishes its examples by build date: the practical pair and the on-device AI book were rebuilt with current code, while the other six are v2.0.0 release-time artifacts. That distinction matters when you evaluate output, because only the rebuilt ones reflect numeral covers, multi-spread contents and the global scale fix.

Upgrade cost is bounded by the pinning. @antv/infographic is fixed at 0.2.19 inside package.json, and the SSR bundle is vendored into the repository, so the diagram renderer does not move unless someone moves it. Style packs carry measured contracts, and G16-SYNC compares the real theme against the declaration, so a pack edited by hand will fail the build rather than drift. The mutation suite is the part that makes version bumps expensive for the maintainer: any change to gate sensitivity has to keep 25 judgement axes, including the M0 control, behaving correctly.

Editorial conclusion

Adopt bookforge if you already work inside Claude Code or Codex, write in Korean, and want a PDF with cover, leader-dot table of contents, chapter dividers, running heads and colophon without hand-building a layout. Do not adopt it if you need output in English, if you cannot install Typst 0.14+, Python with PyMuPDF and markdown-it-py, and a global Playwright Chromium, or if you expect the gates to catch content problems rather than typographic ones. Before committing, open the nine example PDFs linked from the README and check the two that were rebuilt with current code, then read references/pagination.md to see whether its measured rules match the book you have in mind.

Frequently asked questions

Official sources

1. gongnyang/bookforge on GitHub
2. Issues
3. README
4. Releases