klartex 0.13.0

PDF generation via LaTeX — structured data in, professional documents out

English version: README.en.md

Klartex

PDF-generering via LaTeX — strukturerad data in, professionella dokument ut.

klartex.se · PyPI · GitHub

Klartex tar JSON-data + mallnamn och producerar PDF via XeLaTeX. Kan användas som Python-bibliotek eller CLI-verktyg.

Mallar

Mall	Beskrivning
_block	Universell blockmotor — agenten komponerar dokumentet fritt
protokoll	Mötesprotokoll med dagordning, beslut och justerare
faktura	Faktura med rader, moms och betalningsinformation
kvitto	Kvitto med enkel radlista, betalsätt och totalbelopp
resultatrakning	Resultaträkning med jämförelseår och noter
balansrakning	Balansräkning med tillgångar och skulder/eget kapital
budgetrapport	Budgetrapport med kontokoder, budget och utfall
sie-exportrapport	Läsbar PDF av SIE4-bokföringsdata

Installation

# Som globalt CLI-verktyg
pipx install klartex

# Eller i ett projekt
pip install klartex

Kräver Python ≥ 3.12 och XeLaTeX (brew install --cask mactex eller apt install texlive-xetex).

Användning

Som Python-bibliotek

from klartex import render

pdf_bytes = render("protokoll", data)

Som CLI

# Rendera (block engine är default)
klartex -d data.json

# Pipe JSON via stdin
cat data.json | klartex

# Med explicit mall
klartex -d data.json -t protokoll

# Med extern sidmall
klartex -d data.json --page-template minforening.tex.jinja

# Lista mallar
klartex templates

# Visa JSON Schema för en mall
klartex schema protokoll

Sidmallar (Page Templates)

Sidmallar styr sidhuvud, sidfot, färger och logotyp. Tre inbyggda finns:

Sidmall	Beskrivning
formal	Organisationsnamn och kontaktinfo i sidhuvud, logotyp, sidnummer i sidfot
clean	Enbart logotyp i sidhuvud, sidnummer i sidfot
none	Inget sidhuvud, enbart sidnummer i sidfot

Egen sidmall

Skapa en .tex.jinja-fil som definierar \fancyhead/\fancyfoot:

\definecolor{brandprimary}{HTML}{2E5A1C}
\definecolor{brandsecondary}{HTML}{555555}
\providecommand{\orgname}{}
\renewcommand{\orgname}{Min Förening}
\makeatletter
\fancyhead[L]{\fontsize{6pt}{9pt}\selectfont\textbf{\orgname}}
\fancyhead[R]{\includegraphics[height=0.855cm]{logo.pdf}}
\fancyfoot[C]{%
    \kx@setlang%
    \fontsize{6pt}{9pt}\selectfont\color{brandsecondary}%
    \doctitle\ \textbullet\ \kx@page\ \thepage\ \kx@of\ \pageref{LastPage}%
}
\makeatother

Använd sedan --page-template minforening.tex.jinja i CLI eller "page_template_source": "..." i API-anrop.

Var logotyper och andra filer hittas skiljer sig mellan de två ytorna:

• CLI med filbaserad sidmall (--page-template <sökväg>, eller autodetekterad <data-stem>.tex.jinja / page_template.tex.jinja): filer hittas relativt till sidmallens egen katalog, med arbetsmappen som fallback. En mall och dess logotyper kan därmed ligga samlade i t.ex. en Branding/-mapp och användas från vilken arbetsmapp som helst. För en symlänkad mall gäller målets katalog.
• API med page_template_source: parametern tar rå text utan sökväg, så det finns ingen mallkatalog att utgå från. Anropare som vill hitta filer utanför arbetsmappen skickar asset_dir=<katalog> till render(); annars gäller arbetsmappen.

Både \includegraphics{logo.pdf} och \includegraphics{./logo.pdf} fungerar, liksom \input{../delat/farger.tex} — relativa referenser utgår från mallens katalog (eller asset_dir, i annat fall arbetsmappen). En skillnad finns dock: namn med ./ eller ../ faller inte tillbaka på arbetsmappen. TeX:s filsökning (Kpathsea) söker aldrig upp sådana namn, utan provar dem rakt av mot xelatex arbetskatalog — och den katalogen är just mallens katalog. Namn utan prefix söks däremot i hela kedjan och hittas även om filen bara ligger i arbetsmappen.

Arkitektur

Klartex har en trelagers-arkitektur:

1. Dokumentnivå — klartex-base.cls hanterar siduppställning och grundläggande sidhuvud/sidfot. Sidmallar (.tex.jinja) injiceras i preambeln och styr färger, logotyp och layout.
2. Komponentnivå — Återanvändbara .sty-paket som ger strukturerade LaTeX-makron (t.ex. klartex-signatureblock.sty, klartex-klausuler.sty, klartex-agenda.sty)
3. Receptnivå — YAML-filer som deklarerar vilka komponenter och innehållsfält som ska kombineras

Renderingsvägar

• Recipe-mallar (protokoll, faktura, kvitto) — YAML-recept som deklarerar komponenter och mappningar
• Block engine (_block) — Agenten komponerar body[] fritt från typade block

Skapa en YAML-receptmall

Skapa en recipe.yaml i mallens katalog (t.ex. klartex/templates/min-mall/recipe.yaml):

template:
  name: min-mall
  description: "Beskrivning av mallen"
  lang: sv

document:
  title: "{{ data.title }}"
  page_template: formal
  metadata:
    - label: "Datum:"
      field: date

components:
  - type: klausuler
    data_map:
      items: agenda_items
    options:
      item_title_field: title
      item_body_field: body

schema: schema.json

Tillgängliga recept-komponenter: heading, description_list, agenda, text, resultatrakning, budgettabell, notapparat, invoice_header, invoice_recipient, invoice_table, payment_info, invoice_note, receipt_header, receipt_table. Block-motsvarigheterna (agenda, description_list, heading, resultatrakning, budgettabell, notapparat, text) renderas via samma delade makron som block-engine-vägen.

Block engine-block: heading, text, list, table, callout, quote, title_page, parties, clause, signatures, description_list, form, columns, agenda, name_roster, resultatrakning, budgettabell, notapparat, page_break, latex.

Årsmötespaket

Blockmotorn kan komponera alla dokument som behövs för ett föreningsårsmöte:

Dokument	Blocktyper
Kallelse + dagordning	heading, description_list, agenda
Verksamhetsberättelse	heading, name_roster, text, signatures
Ekonomisk årsredovisning	heading, text, resultatrakning, notapparat, signatures
Revisionsberättelse	heading, text, signatures
Budget	heading, budgettabell
Valberedningens förslag	heading, name_roster, signatures
Motion	heading, text, clause, signatures
Styrelsens yttrande	heading, text, signatures

Agenten väljer och ordnar block för varje dokument — inga separata mallar behövs. Se tests/fixtures/block_kallelse.json m.fl. för fullständiga exempel.

Licens

MIT