ckb/docs/decisions/0021-convert-module.md
Michał Kopeć c57ddceffd Template 2.2.0: voice and convert modules
- 2.1.0 new opt-in `voice` module (D-0020): skill ckb-voice rewrites every
  prose file written under apply_to (outputs/answers, documents, reports,
  PROJECT-OVERVIEW) in a voice whose profile is a wiki page,
  wiki/voice/<name>.md (type voice-profile); settings in ckb.yaml (mode,
  profile, writer, apply_to, skip, chat); frozen spans never change, vague
  claims flagged not cut; `writer:` delegates to an external rewriting
  skill such as a personal ghost-writer. ckb-module writes a manifest's
  default_config into the entry's config:. Eval ckb-module/install-voice.
- 2.2.0 new opt-in `convert` module (D-0021): skill ckb-convert and
  convert.py turn Markdown into Word/ODT/PDF/HTML through pandoc with a
  house style in templates/styles/; unit tests and eval
  ckb-module/install-convert.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-11 20:57:39 +01:00

4.9 KiB

type tldr status decided_on decided_by affects confidence quality last_updated freshness_window_days retention
decision Markdown leaves the KB as Word/ODT/PDF/HTML through an opt-in `convert` module — pandoc does the conversion, the look is a named reference .docx in templates/styles/ that a stdlib script can build or adjust from a few settings or copy from a company .docx/.dotx, PDF and ODT go through LibreOffice from the styled .docx so every format matches, and the Markdown stays the source. accepted 2026-11-11 Michał Kopeć .agents/modules/convert/, tests/unit/test_convert.py, tests/evals/ckb-module/install-convert/, README.md, docs/MANUAL.md, docs/CHANGELOG.md 0.75 0.8 2026-11-11 365 high

D-0021 — A convert module for documents that leave as Office files

Status: Accepted · Decided: 2026-11-11 · Deciders: Michał Kopeć

Context

ckb-document, kept answers and reports all write Markdown. The people they go to want a Word file or a PDF in the company's look. ckb-document Step 4 says to make a .docx "with the general document skills", which leaves the fonts, sizes and margins to whatever the agent picks each time. Michał wanted a pandoc front end with design templates, so users get a consistent document without thinking about typography.

Decision

  1. An opt-in module (D-0001 pattern), convert, with one skill, ckb-convert, and one stdlib script, convert.py. pandoc is a system tool not every KB needs.
  2. A style is a reference .docx in templates/styles/<name>.docx, pandoc's own mechanism: it takes styles, page setup, header and footer from it and ignores the text. Optional <name>.odt and <name>.css cover ODT and HTML. templates/ already holds the user's document templates and isn't a retrieval layer. ckb-document lists only templates/*.md, so the subfolder doesn't clash.
  3. Styles from settings, not by hand. new-style/edit-style copy pandoc's default reference and patch body font, heading font, body size, heading colour, paper (A4/Letter) and margins straight into styles.xml, theme1.xml and the body sectPr, keeping the schema's child order so Word opens the result. --from takes a company .docx or .dotx (content type rewritten) and check-style lists the styles pandoc uses that it lacks. Anything richer (logos, cover pages) is edited in Word, and the skill says so.
  4. One look for every format. PDF and ODT are produced by LibreOffice from the styled .docx, in a private profile so an open LibreOffice doesn't block it. Without LibreOffice, PDF falls back to a pandoc PDF engine and the skill reports that the style wasn't applied.
  5. KB Markdown is cleaned for an outside reader, in the copy only: frontmatter → title/author/date/lang metadata (e-mail dropped), the leading # H1 → title, template comments dropped, wikilinks and KB-path links → text (keep_links opts out), code blocks untouched.
  6. The Markdown stays the source, always kept. An existing converted file is never overwritten without --force; the skill asks, since it may have been edited in Word.
  7. Settings in ckb.yaml through default_config (D-0020): style, format, out_dir, toc, number_sections, keep_links.
  8. Hook through the AGENTS.md block, as D-0020 did: any request for an Office/PDF file goes through ckb-convert, after ckb-voice when that is installed. ckb-document is unchanged.
  9. pandoc is a non-blocking dependency of the install. The module is committed and shared, and a teammate without pandoc gets install instructions at first use rather than a blocked install for everyone.

Alternatives considered

  • python-docx or the general docx skill to build documents directly. These need a third-party package or produce a different look per run, and they can't read the Markdown the KB already has. pandoc is the standard tool for exactly this conversion.
  • Ship a binary house.docx in the module. A binary in the template repo, and a single fixed look. Generating it from pandoc's default plus settings keeps the repo text-only and the look adjustable.
  • pandoc's LaTeX route for PDF. It needs a TeX install and a second style definition that drifts from the Word one. LibreOffice reuses the .docx.
  • Edit ckb-document to convert. That would cover one producer only. Answers, reports and wiki pages need conversion too.

Consequences

  • No new page types or fields; no schema change.
  • Fonts aren't embedded in .docx; a rare font shows as a substitute. The README and skill say so.
  • The XML patching covers the settings listed and nothing else. A company template with unusual structure gets check-style and a pointer to Word.
  • Tests: tests/unit/test_convert.py (clean-up always; style patching and conversion when pandoc is present) and an install eval, ckb-module/install-convert, not yet run.