- 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>
82 lines
3.3 KiB
Markdown
82 lines
3.3 KiB
Markdown
# `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/<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"):
|
||
|
||
```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.
|