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

Installation

# Som globalt CLI-verktyg
pipx install klartex

# Eller i ett projekt
pip install klartex

Kräver Python ≥ 3.12 och XeLaTeX.

# macOS
brew install --cask mactex

# Debian/Ubuntu
sudo apt install texlive-xetex texlive-fonts-recommended \
  texlive-latex-extra texlive-latex-recommended texlive-science texlive-plain-generic

Paketuppsättningen för Debian/Ubuntu är densamma som CI installerar, alltså den som hela testsviten körs mot. texlive-xetex ensamt räcker inte — bland annat ulem (i texlive-plain-generic), tcolorbox och siunitx behövs för att rendera.

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:

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:

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