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

86 lines
3.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# Moduł `convert`
*Przeczytaj w: [English](README.md) | **Polski***
Opcjonalny. Instalacja: „install the convert module”, usunięcie: „uninstall
the convert module”. Dopóki nie jest zainstalowany, nic z tego folderu nie
działa.
## Co robi
Baza pisze w Markdownie. Ludzie, do których coś wysyłasz, chcą pliku Worda
albo PDF-a, który wygląda jak reszta dokumentów w firmie. Ten moduł zamienia
dowolny plik Markdown z bazy na **`.docx`, `.odt`, PDF lub HTML** przez
[pandoc](https://pandoc.org), w **stylu firmowym**, więc nikt nie dobiera
ręcznie czcionek, rozmiarów ani marginesów.
| Skill | Co robi |
|---|---|
| `ckb-convert` | Konwertuje plik w wybranym stylu; tworzy styl z kilku ustawień albo z firmowego szablonu Worda; zmienia, sprawdza i wypisuje style. |
Powiedz „give me the status report as a Word file” albo „convert this answer
to PDF”. Za pierwszym razem padnie jedno pytanie o to, jak ma wyglądać styl
firmowy.
## Style
Styl to plik Worda, `templates/styles/<nazwa>.docx`. pandoc bierze z niego
czcionki, rozmiary, kolory, odstępy, format strony, marginesy, nagłówek i
stopkę, a jego treść pomija. Styl można zdobyć na trzy sposoby:
- **Opisać go**: „make a house style with Georgia 11pt, navy headings, A4”.
- **Przynieść własny**: „use Company.dotx as the house style”. Agent go
skopiuje i powie, których stylów potrzebnych pandocowi brakuje w szablonie.
- **Poprawić ręcznie** w Wordzie lub LibreOffice: zmieniać *style* (Normal,
Body Text, Title, Heading 1–6, Table), nie treść, i zapisać jako `.docx`.
Stylów może być kilka („convert it in the board style”). `<nazwa>.css`
ustala wygląd HTML, a opcjonalny `<nazwa>.odt` wygląd ODT.
PDF i ODT powstają ze sformatowanego `.docx` przez LibreOffice, więc
wszystkie formaty wyglądają tak samo. Bez LibreOffice PDF robi silnik PDF
pandoca i styl Worda nie jest stosowany. Agent o tym powie.
## Co się zmienia po drodze
Plik Markdown nigdy się nie zmienia i zawsze zostaje. W skonwertowanej
kopii:
- frontmatter staje się tytułem, autorem (bez adresu e-mail) i datą, a
pierwszy nagłówek `#` staje się tytułem, gdy frontmatter go nie ma;
- komentarze `<!-- … -->` pozostałe z szablonu znikają;
- `[[Wikilinki]]` i linki do ścieżek w bazie stają się zwykłym tekstem, bo w
pliku Worda byłyby martwe („keep the links” je zostawia); linki do stron
WWW zostają;
- bloki kodu, tabele, listy zadań i obrazy przechodzą bez zmian.
## Ustawienia
W `ckb.yaml`, we wpisie modułu. Zmienia się je prośbą („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/ # plik już leżący w outputs/ trafia obok siebie
toc: false
number_sections: false
keep_links: false
```
## Wymagania
- **pandoc** do każdej konwersji. Instalacja modułu go nie wymaga, więc
osoba z zespołu bez pandoca nadal może sklonować bazę; przy pierwszej
konwersji dowie się, jak go zainstalować.
- **LibreOffice**, opcjonalnie, do PDF i ODT w stylu firmowym.
- Python 3.8+, jak każdy skrypt bazy. Nic nie jest instalowane bez pytania.
## Warto wiedzieć
- **Czcionki nie są osadzane** w `.docx`. Wybieraj czcionki, które mają
czytelnicy.
- **Odinstalowanie zostawia style**: `templates/styles/` zostaje.
- **Szablony z makrami** (`.docm`, `.dotm`) są odrzucane; najpierw zapisz
kopię jako `.docx` lub `.dotx`.