klartex 0.10.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, CLI-verktyg eller HTTP-tjänst.

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
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

# Starta HTTP-server
klartex serve

Som Docker-image

Officiell multi-arch-image (linux/amd64 + linux/arm64) publiceras till GitHub Container Registry vid varje release:

docker run --rm -p 8000:8000 ghcr.io/swedev/klartex:latest
# eller låst version: ghcr.io/swedev/klartex:0.9.8

Imagen startar HTTP-tjänsten på port 8000. Tillgängliga taggar: X.Y.Z (exakt version), X.Y (senaste i minor-serien) och latest.

Som HTTP-tjänst

klartex serve --port 8000

# Rendera PDF
curl -X POST http://localhost:8000/render \
  -H "Content-Type: application/json" \
  -d '{"template": "protokoll", "data": {...}}' \
  -o output.pdf

# Rendera med extern sidmall
curl -X POST http://localhost:8000/render \
  -H "Content-Type: application/json" \
  -d '{"template": "_block", "data": {...}, "page_template_source": "\\definecolor{brandprimary}{HTML}{2E5A1C}\\n..."}' \
  -o output.pdf

# Lista mallar
curl http://localhost:8000/templates

# Hämta schema
curl http://localhost:8000/templates/protokoll/schema

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. Logotyper och andra filer hittas relativt till 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) — 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. 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