ckb/.agents/modules/convert/README.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

3.3 KiB
Raw Permalink Blame History

convert module

Read this in: English | Polski

Opt-in. Install with "install the convert module"; remove with "uninstall the convert module". Nothing in here is active until installed.

What it does

The KB writes Markdown. The people you send things to want a Word file or a PDF that looks like the rest of your company's documents. This module turns any Markdown file in the KB into .docx, .odt, PDF or HTML through pandoc, in a house style, so nobody picks fonts, sizes or margins by hand.

Skill Does
ckb-convert Converts a file in a named style; creates a style from a few settings or from your company's Word template; changes, checks and lists styles.

Say "give me the status report as a Word file" or "convert this answer to PDF". The first time, it asks once how the house style should look.

Styles

A style is a Word file, templates/styles/<name>.docx. pandoc takes fonts, sizes, colours, spacing, page size, margins, header and footer from it and ignores its text. You get one in one of three ways:

  • Describe it: "make a house style with Georgia 11pt, navy headings, A4".
  • Bring your own: "use Company.dotx as the house style". The agent copies it in and tells you which styles pandoc needs that your template lacks.
  • Edit it by hand in Word or LibreOffice: change the styles (Normal, Body Text, Title, Heading 1–6, Table), not the text, and save as .docx.

Several styles can live side by side ("convert it in the board style"). <name>.css styles HTML, and an optional <name>.odt styles ODT directly.

PDF and ODT are made from the styled .docx with LibreOffice, so all formats look the same. Without LibreOffice, PDF falls back to a pandoc PDF engine and won't follow the Word style. You'll be told when that happens.

What changes on the way

The Markdown file is never changed and is always kept. In the converted copy:

  • frontmatter becomes the title, author (without the e-mail) and date, and the first # Heading becomes the title when there's none;
  • <!-- comments --> left over from a template are dropped;
  • [[Wikilinks]] and links to KB paths become plain text, because they'd be dead in a Word file (say "keep the links" to keep them); web links stay;
  • code blocks, tables, task lists and images come through as they are.

Settings

In ckb.yaml, under the module's entry. Change them by asking ("make PDF the default", "always add a table of contents"):

config:
  style: house                # templates/styles/house.docx
  format: docx                # docx | odt | pdf | html
  out_dir: outputs/documents/ # a file already in outputs/ converts beside itself
  toc: false
  number_sections: false
  keep_links: false

Requirements

  • pandoc, for every conversion. The install doesn't need it, so a teammate without it can still clone the KB; they're told how to get it the first time they convert.
  • LibreOffice, optional, for PDF and ODT in the house style.
  • Python 3.8+ like every other KB script. Nothing is installed without asking.

Good to know

  • Fonts aren't embedded in a .docx. Choose fonts your readers have.
  • Uninstalling keeps your styles: templates/styles/ stays.
  • Macro templates (.docm, .dotm) are refused; save a copy as .docx or .dotx first.