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

3.5 KiB
Raw Blame History

Moduł convert

Przeczytaj w: English | 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, 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”):

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.