# `convert` module *Read this in: **English** | [Polski](README.pl.md)* 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](https://pandoc.org), 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/.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"). `.css` styles HTML, and an optional `.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; - `` 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"): ```yaml 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.