praxigraph 1.0.0__py3-none-any.whl

praxigraph/__init__.py

@@ -0,0 +1,3 @@
+"""Praxigraph: Markdown-driven business documents on your own letterhead."""
+
+__version__ = "1.0.0"

praxigraph/builder.py

@@ -0,0 +1,73 @@
+"""Orchestrate the build: load documents, write HTML, render PDFs."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .config import Config, ConfigError
+from .document import Document, load_document
+from .pdf import find_chrome, finalize_pdf, render_pdf
+from .render import render_document
+
+
+@dataclass
+class BuildResult:
+    document: Document
+    html_path: Path
+    pdf_path: Path | None
+    ok: bool
+
+
+def load_documents(cfg: Config) -> list[Document]:
+    documents = [load_document(path) for path in cfg.documents]
+    slugs = [doc.slug for doc in documents]
+    for slug in slugs:
+        if slugs.count(slug) > 1:
+            raise ConfigError(f"Duplicate document slug '{slug}' "
+                              f"(set a distinct 'slug' in the front matter).")
+    return documents
+
+
+def pdf_name(cfg: Config, doc: Document, datestamp: str | None = None) -> str:
+    if not cfg.output.date_prefix:
+        return f"{doc.slug}.pdf"
+    return f"{datestamp or doc.date.isoformat()}_{doc.slug}.pdf"
+
+
+def build(cfg: Config, slugs: list[str] | None = None, html_only: bool = False,
+          datestamp: str | None = None) -> list[BuildResult]:
+    documents = load_documents(cfg)
+    if slugs:
+        known = {doc.slug for doc in documents}
+        for slug in slugs:
+            if slug not in known:
+                raise ConfigError(f"Unknown document '{slug}' "
+                                  f"(available: {', '.join(sorted(known))})")
+        documents = [doc for doc in documents if doc.slug in slugs]
+    if not documents:
+        raise ConfigError("No documents to build.")
+
+    chrome = None if html_only else find_chrome(cfg.chrome)
+    cfg.output.html_dir.mkdir(parents=True, exist_ok=True)
+    if not html_only:
+        cfg.output.pdf_dir.mkdir(parents=True, exist_ok=True)
+
+    results = []
+    for doc in documents:
+        html_path = cfg.output.html_dir / f"{doc.slug}.html"
+        html_path.write_text(render_document(cfg, doc), encoding="utf-8")
+        if html_only:
+            print(f"  HTML {html_path}")
+            results.append(BuildResult(doc, html_path, None, True))
+            continue
+        pdf_path = cfg.output.pdf_dir / pdf_name(cfg, doc, datestamp)
+        ok = render_pdf(chrome, html_path, pdf_path)
+        if ok:
+            finalize_pdf(pdf_path, title=f"{doc.doc_type}: {doc.title}",
+                         author=cfg.letterhead.name)
+            print(f"  PDF  {pdf_path}")
+        else:
+            print(f"  FAILED {pdf_path}")
+        results.append(BuildResult(doc, html_path, pdf_path, ok))
+    return results

praxigraph/cli.py

@@ -0,0 +1,60 @@
+"""Command line: `praxigraph build` and `praxigraph validate`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from .builder import build, load_documents
+from .config import ConfigError, load_config
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="praxigraph",
+        description="Markdown-driven business documents on your own letterhead "
+                    "(HTML -> PDF via Chrome).")
+    parser.add_argument("--version", action="version",
+                        version=f"praxigraph {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    b = sub.add_parser("build", help="generate HTML and PDFs")
+    b.add_argument("-c", "--config", default="config.yaml", help="path to the config.yaml")
+    b.add_argument("--doc", action="append",
+                   help="build only this document slug (repeatable)")
+    b.add_argument("--html-only", action="store_true",
+                   help="generate HTML only, no Chrome/PDF")
+    b.add_argument("--date", default=None,
+                   help="override the date prefix of the PDF file names (YYYY-MM-DD)")
+
+    v = sub.add_parser("validate", help="check config and documents")
+    v.add_argument("-c", "--config", default="config.yaml", help="path to the config.yaml")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = _parser().parse_args(argv)
+    try:
+        cfg = load_config(args.config)
+        if args.command == "validate":
+            documents = load_documents(cfg)
+            print(f"OK: configuration and {len(documents)} document(s) are valid.")
+            return 0
+
+        results = build(cfg, slugs=args.doc, html_only=args.html_only,
+                        datestamp=args.date)
+        failed = [r for r in results if not r.ok]
+        if failed:
+            print(f"Error: {len(failed)} document(s) could not be rendered.",
+                  file=sys.stderr)
+            return 1
+        print("done.")
+        return 0
+    except (ConfigError, RuntimeError) as exc:
+        print(f"Error: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

praxigraph/config.py

@@ -0,0 +1,162 @@
+"""Load and validate the steering file config.yaml."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+
+class ConfigError(Exception):
+    """Raised for any invalid or missing configuration value."""
+
+
+#: German defaults; every label can be overridden under `labels:`.
+DEFAULT_LABELS = {
+    "number": "Nr.",
+    "date": "Datum",
+    "phone": "Tel.",
+    "email": "E-Mail",
+    "web": "Web",
+    "vat_id": "USt-IdNr.",
+    "tax_number": "Steuernr.",
+    "bank": "Bank",
+    "iban": "IBAN",
+    "bic": "BIC",
+}
+
+_OPTIONAL_SECTIONS = ("contact", "tax", "bank", "signature")
+
+
+@dataclass
+class Letterhead:
+    name: str
+    street: str
+    zip: str
+    city: str
+    tagline: str | None = None
+    country: str | None = None
+    logo: Path | None = None
+    contact: dict = field(default_factory=dict)   # phone, email, website
+    tax: dict = field(default_factory=dict)       # vat_id, tax_number
+    bank: dict = field(default_factory=dict)      # name, iban, bic
+    signature: dict = field(default_factory=dict)  # name, place
+
+
+@dataclass
+class OutputConfig:
+    html_dir: Path
+    pdf_dir: Path
+    date_prefix: bool = True
+
+
+@dataclass
+class Config:
+    base: Path
+    letterhead: Letterhead
+    documents: list[Path]
+    theme: str = "letter"
+    color: str | None = None
+    lang: str = "de"
+    date_format: str = "%d.%m.%Y"
+    labels: dict = field(default_factory=lambda: dict(DEFAULT_LABELS))
+    chrome: str | None = None
+    output: OutputConfig | None = None
+
+
+def _require(data: dict, key: str, where: str) -> object:
+    if key not in data or data[key] in (None, ""):
+        raise ConfigError(f"Missing required field '{key}' in {where}.")
+    return data[key]
+
+
+def _load_letterhead(data: dict, base: Path) -> Letterhead:
+    if not isinstance(data, dict):
+        raise ConfigError("'letterhead' must be a mapping.")
+    head = Letterhead(
+        name=str(_require(data, "name", "letterhead")),
+        street=str(_require(data, "street", "letterhead")),
+        zip=str(_require(data, "zip", "letterhead")),
+        city=str(_require(data, "city", "letterhead")),
+        tagline=data.get("tagline"),
+        country=data.get("country"),
+    )
+    if data.get("logo"):
+        logo = (base / str(data["logo"])).resolve()
+        if not logo.exists():
+            raise ConfigError(f"Logo file not found: {logo}")
+        head.logo = logo
+    for section in _OPTIONAL_SECTIONS:
+        value = data.get(section) or {}
+        if not isinstance(value, dict):
+            raise ConfigError(f"'letterhead.{section}' must be a mapping.")
+        setattr(head, section, {k: str(v) for k, v in value.items() if v not in (None, "")})
+    return head
+
+
+def _resolve_documents(value: object, base: Path) -> list[Path]:
+    """`documents:` is either a directory containing *.md or a list of paths."""
+    if value is None:
+        value = "documents"
+    if isinstance(value, str):
+        directory = (base / value).resolve()
+        if not directory.is_dir():
+            raise ConfigError(f"Documents directory not found: {directory}")
+        return sorted(directory.glob("*.md"))
+    if isinstance(value, list):
+        paths = []
+        for item in value:
+            path = (base / str(item)).resolve()
+            if not path.is_file():
+                raise ConfigError(f"Document not found: {path}")
+            paths.append(path)
+        return paths
+    raise ConfigError("'documents' must be a directory name or a list of files.")
+
+
+def load_config(path: str | Path) -> Config:
+    path = Path(path)
+    if not path.is_file():
+        raise ConfigError(f"Config file not found: {path}")
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"Invalid YAML in {path}: {exc}") from exc
+    if not isinstance(data, dict):
+        raise ConfigError(f"{path} must contain a YAML mapping.")
+
+    base = path.parent.resolve()
+    letterhead = _load_letterhead(_require(data, "letterhead", str(path)), base)
+
+    labels = dict(DEFAULT_LABELS)
+    overrides = data.get("labels") or {}
+    if not isinstance(overrides, dict):
+        raise ConfigError("'labels' must be a mapping.")
+    for key, value in overrides.items():
+        if key not in DEFAULT_LABELS:
+            raise ConfigError(f"Unknown label '{key}' "
+                              f"(known: {', '.join(sorted(DEFAULT_LABELS))})")
+        labels[key] = str(value)
+
+    out = data.get("output") or {}
+    if not isinstance(out, dict):
+        raise ConfigError("'output' must be a mapping.")
+    output = OutputConfig(
+        html_dir=(base / str(out.get("html_dir", ".build/html"))).resolve(),
+        pdf_dir=(base / str(out.get("pdf_dir", "pdf"))).resolve(),
+        date_prefix=bool(out.get("date_prefix", True)),
+    )
+
+    return Config(
+        base=base,
+        letterhead=letterhead,
+        documents=_resolve_documents(data.get("documents"), base),
+        theme=str(data.get("theme", "letter")),
+        color=str(data["color"]) if data.get("color") else None,
+        lang=str(data.get("lang", "de")),
+        date_format=str(data.get("date_format", "%d.%m.%Y")),
+        labels=labels,
+        chrome=str(data["chrome"]) if data.get("chrome") else None,
+        output=output,
+    )

praxigraph/document.py

@@ -0,0 +1,91 @@
+"""Load a Markdown document with YAML front matter."""
+
+from __future__ import annotations
+
+import datetime as dt
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from .config import ConfigError
+
+_FRONT_MATTER = re.compile(r"\A---\s*\n(.*?)\n---\s*\n", re.DOTALL)
+
+
+@dataclass
+class Document:
+    path: Path
+    slug: str
+    doc_type: str          # e.g. "Protokoll", "Bericht", "Bescheinigung"
+    title: str
+    date: dt.date
+    body_md: str
+    number: str | None = None
+    recipient: str | None = None
+    meta: list[dict] = field(default_factory=list)  # extra {label, value} rows
+    signature: bool = False
+    lang: str | None = None
+
+
+def _parse_date(value: object, path: Path) -> dt.date:
+    """Front matter dates: a YAML date, or an ISO string YYYY-MM-DD."""
+    if isinstance(value, dt.datetime):
+        return value.date()
+    if isinstance(value, dt.date):
+        return value
+    if isinstance(value, str):
+        try:
+            return dt.date.fromisoformat(value.strip())
+        except ValueError:
+            pass
+    raise ConfigError(f"{path}: 'date' must be a date (YYYY-MM-DD), got {value!r}.")
+
+
+def _parse_meta(value: object, path: Path) -> list[dict]:
+    if value is None:
+        return []
+    if not isinstance(value, list):
+        raise ConfigError(f"{path}: 'meta' must be a list of {{label, value}} entries.")
+    meta = []
+    for entry in value:
+        if not isinstance(entry, dict) or "label" not in entry or "value" not in entry:
+            raise ConfigError(f"{path}: every 'meta' entry needs 'label' and 'value'.")
+        meta.append({"label": str(entry["label"]), "value": str(entry["value"])})
+    return meta
+
+
+def load_document(path: str | Path) -> Document:
+    path = Path(path)
+    if not path.is_file():
+        raise ConfigError(f"Document not found: {path}")
+    text = path.read_text(encoding="utf-8")
+    match = _FRONT_MATTER.match(text)
+    if not match:
+        raise ConfigError(f"{path}: missing YAML front matter (--- block at the top).")
+    try:
+        front = yaml.safe_load(match.group(1))
+    except yaml.YAMLError as exc:
+        raise ConfigError(f"{path}: invalid YAML front matter: {exc}") from exc
+    if not isinstance(front, dict):
+        raise ConfigError(f"{path}: front matter must be a YAML mapping.")
+
+    for key in ("type", "title", "date"):
+        if key not in front or front[key] in (None, ""):
+            raise ConfigError(f"{path}: missing required front matter field '{key}'.")
+
+    recipient = front.get("recipient")
+    return Document(
+        path=path,
+        slug=str(front.get("slug") or path.stem),
+        doc_type=str(front["type"]),
+        title=str(front["title"]),
+        date=_parse_date(front["date"], path),
+        body_md=text[match.end():],
+        number=str(front["number"]) if front.get("number") not in (None, "") else None,
+        recipient=str(recipient).rstrip() if recipient not in (None, "") else None,
+        meta=_parse_meta(front.get("meta"), path),
+        signature=bool(front.get("signature", False)),
+        lang=str(front["lang"]) if front.get("lang") else None,
+    )

praxigraph/pdf.py

@@ -0,0 +1,113 @@
+"""PDF generation via Chrome headless, plus page numbers and metadata (pypdf)."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+CHROME_CANDIDATES = [
+    "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+    "/Applications/Chromium.app/Contents/MacOS/Chromium",
+    r"C:\Program Files\Google\Chrome\Application\chrome.exe",
+    r"C:\Program Files (x86)\Google\Chrome\Application\chrome.exe",
+    "/usr/bin/google-chrome",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+]
+
+
+def find_chrome(configured: str | None = None) -> str:
+    """Find Chrome/Chromium: config value > environment variable > known paths > PATH."""
+    candidates = [configured, os.environ.get("PRAXIGRAPH_CHROME"), *CHROME_CANDIDATES]
+    for candidate in candidates:
+        if candidate and os.path.exists(candidate):
+            return candidate
+    for name in ("google-chrome", "chromium", "chromium-browser", "chrome"):
+        found = shutil.which(name)
+        if found:
+            return found
+    raise RuntimeError(
+        "Chrome/Chromium not found. Set the path in the config.yaml under "
+        "'chrome:' or via the PRAXIGRAPH_CHROME environment variable.")
+
+
+def render_pdf(chrome: str, html_path: Path, pdf_path: Path) -> bool:
+    subprocess.run(
+        [chrome, "--headless=new", "--disable-gpu", "--no-sandbox",
+         "--virtual-time-budget=12000", "--run-all-compositor-stages-before-draw",
+         "--no-pdf-header-footer",
+         f"--print-to-pdf={pdf_path}", str(html_path)],
+        check=False, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+    return pdf_path.exists() and pdf_path.stat().st_size > 0
+
+
+#: Helvetica advance widths per 1000 units of em, for the only characters a
+#: page-number stamp can contain. Helvetica is one of the PDF base-14 fonts,
+#: so it needs no embedding and no font file to measure against.
+_STAMP_WIDTHS = {**{str(d): 556 for d in range(10)}, " ": 278, "/": 278}
+
+_STAMP_SIZE = 8
+#: Baseline in points from the page bottom: just above the letterhead footer
+#: (which occupies the lowest ~24 mm), right-aligned with the content area.
+_STAMP_BASELINE = 74
+#: Right content edge in points from the right paper edge (15 mm).
+_STAMP_RIGHT_MARGIN = 42.5
+_STAMP_COLOR = "0.5 0.55 0.62"
+
+
+def finalize_pdf(pdf_path: Path, title: str | None = None,
+                 author: str | None = None) -> bool:
+    """Post-process a rendered PDF: page numbers and document metadata.
+
+    Inserts a subtle page number 'i / n' at the bottom right, just above the
+    letterhead footer, and sets the PDF title/author metadata. Returns False
+    if pypdf is missing, leaving the PDF unchanged.
+    """
+    try:
+        import pypdf
+        from pypdf.generic import DecodedStreamObject, DictionaryObject, NameObject
+    except ImportError:
+        return False
+
+    writer = pypdf.PdfWriter(clone_from=pypdf.PdfReader(pdf_path))
+    total = len(writer.pages)
+    helvetica = DictionaryObject({
+        NameObject("/Type"): NameObject("/Font"),
+        NameObject("/Subtype"): NameObject("/Type1"),
+        NameObject("/BaseFont"): NameObject("/Helvetica"),
+    })
+    for number, page in enumerate(writer.pages, 1):
+        text = f"{number} / {total}"
+        width = sum(_STAMP_WIDTHS[c] for c in text) / 1000 * _STAMP_SIZE
+        box = page.mediabox
+        x = float(box.right) - _STAMP_RIGHT_MARGIN - width
+        y = float(box.bottom) + _STAMP_BASELINE
+
+        fonts = page.setdefault(NameObject("/Resources"), DictionaryObject()) \
+                    .setdefault(NameObject("/Font"), DictionaryObject())
+        fonts[NameObject("/PraxiHelv")] = helvetica
+
+        contents = page.get_contents()
+        body = contents.get_data() if contents is not None else b""
+        stamped = DecodedStreamObject()
+        # The page content is wrapped in q/Q before the stamp is appended:
+        # Chrome emits a global `cm` transformation with no enclosing q, which
+        # would otherwise scale and mirror the stamp along with the page.
+        stamped.set_data(
+            b"q\n" + body + b"\nQ\n"
+            + f"q BT /PraxiHelv {_STAMP_SIZE} Tf {_STAMP_COLOR} rg "
+              f"1 0 0 1 {x:.2f} {y:.2f} Tm ({text}) Tj ET Q\n".encode("ascii"))
+        page.replace_contents(stamped)
+        page.compress_content_streams()
+
+    metadata = {"/Creator": "praxigraph"}
+    if title:
+        metadata["/Title"] = title
+    if author:
+        metadata["/Author"] = author
+    writer.add_metadata(metadata)
+    with open(pdf_path, "wb") as fh:
+        writer.write(fh)
+    return True

praxigraph/render.py

@@ -0,0 +1,191 @@
+"""Assemble the HTML for one document: letterhead + Markdown body."""
+
+from __future__ import annotations
+
+import base64
+import html
+import re
+from pathlib import Path
+
+import markdown
+
+from .config import Config, ConfigError, Letterhead
+from .document import Document
+
+THEMES_DIR = Path(__file__).parent / "themes"
+
+_MD_EXTENSIONS = ["tables", "fenced_code", "sane_lists"]
+
+_IMAGE_TYPES = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg",
+                ".webp": "image/webp"}
+
+
+def _esc(value: str) -> str:
+    return html.escape(str(value), quote=False)
+
+
+def load_theme(theme: str, base: Path) -> str:
+    """A bundled theme name, or a path to a custom .css file."""
+    bundled = THEMES_DIR / f"{theme}.css"
+    if bundled.is_file():
+        return bundled.read_text(encoding="utf-8")
+    custom = (base / theme).resolve()
+    if custom.is_file():
+        return custom.read_text(encoding="utf-8")
+    names = ", ".join(sorted(p.stem for p in THEMES_DIR.glob("*.css")))
+    raise ConfigError(f"Theme '{theme}' not found (bundled: {names}).")
+
+
+def _logo_html(logo: Path) -> str:
+    """SVG is inlined (keeps gradients crisp), raster images become data URIs."""
+    suffix = logo.suffix.lower()
+    if suffix == ".svg":
+        svg = logo.read_text(encoding="utf-8")
+        svg = re.sub(r"<\?xml[^>]*\?>", "", svg).strip()
+        return f'<div class="logo">{svg}</div>'
+    mime = _IMAGE_TYPES.get(suffix)
+    if mime is None:
+        raise ConfigError(f"Unsupported logo format '{suffix}' "
+                          f"(supported: .svg, {', '.join(_IMAGE_TYPES)}).")
+    data = base64.b64encode(logo.read_bytes()).decode("ascii")
+    return f'<div class="logo"><img src="data:{mime};base64,{data}" alt=""></div>'
+
+
+def _firm_line(head: Letterhead) -> str:
+    return _esc(head.name) + (f" – {_esc(head.tagline)}" if head.tagline else "")
+
+
+def _header_html(head: Letterhead) -> str:
+    inner = _logo_html(head.logo) if head.logo else \
+        f'<div class="logo-fallback">{_firm_line(head)}</div>'
+    return f'<header class="letterhead-header">{inner}</header>'
+
+
+def _footer_section(rows: list[tuple[str | None, str]]) -> str:
+    parts = []
+    for label, value in rows:
+        prefix = f'<span class="footer-label">{_esc(label)}</span> ' if label else ""
+        parts.append(f'<div class="footer-row">{prefix}'
+                     f'<span class="footer-value">{value}</span></div>')
+    return f'<div class="footer-section">{"".join(parts)}</div>'
+
+
+def _footer_html(head: Letterhead, labels: dict) -> str:
+    address = [(None, _esc(head.name)
+                      + (f"<br>{_esc(head.tagline)}" if head.tagline else "")),
+               (None, _esc(head.street)),
+               (None, f"{_esc(head.zip)} {_esc(head.city)}")]
+    if head.country:
+        address.append((None, _esc(head.country)))
+    sections = [_footer_section(address)]
+
+    contact = []
+    if head.contact.get("phone"):
+        contact.append((labels["phone"], _esc(head.contact["phone"])))
+    if head.contact.get("email"):
+        email = head.contact["email"]
+        contact.append((labels["email"],
+                        f'<a href="mailto:{html.escape(email)}">{_esc(email)}</a>'))
+    if head.contact.get("website"):
+        website = head.contact["website"]
+        url = website if website.startswith(("http://", "https://")) \
+            else f"https://{website}"
+        contact.append((labels["web"],
+                        f'<a href="{html.escape(url)}">{_esc(website)}</a>'))
+    if contact:
+        sections.append(_footer_section(contact))
+
+    tax = [(labels[key], _esc(head.tax[key]))
+           for key in ("vat_id", "tax_number") if head.tax.get(key)]
+    if tax:
+        sections.append(_footer_section(tax))
+
+    bank = [(labels[key], _esc(head.bank[field]))
+            for key, field in (("bank", "name"), ("iban", "iban"), ("bic", "bic"))
+            if head.bank.get(field)]
+    if bank:
+        sections.append(_footer_section(bank))
+
+    return ('<footer class="letterhead-footer"><div class="footer-grid">'
+            + "".join(sections) + "</div></footer>")
+
+
+def _infobox_html(doc: Document, cfg: Config) -> str:
+    rows = []
+    if doc.number:
+        rows.append((cfg.labels["number"], doc.number))
+    rows.append((cfg.labels["date"], doc.date.strftime(cfg.date_format)))
+    rows.extend((entry["label"], entry["value"]) for entry in doc.meta)
+    cells = "".join(
+        f'<tr><td class="infobox-label">{_esc(label)}</td>'
+        f'<td class="infobox-value">{_esc(value)}</td></tr>'
+        for label, value in rows)
+    return f'<div class="infobox"><table>{cells}</table></div>'
+
+
+def _first_page_head(doc: Document, cfg: Config) -> str:
+    head = cfg.letterhead
+    recipient = ""
+    modifier = ""
+    if doc.recipient:
+        modifier = " with-recipient"
+        lines = "<br>".join(_esc(line) for line in doc.recipient.splitlines())
+        recipient = (
+            f'<div class="recipient-block">'
+            f'<div class="addressline">{_firm_line(head)}<br>'
+            f'{_esc(head.street)} – {_esc(head.zip)} {_esc(head.city)}</div>'
+            f'<div class="recipient">{lines}</div></div>')
+    return (f'<div class="first-page-head{modifier}">{recipient}'
+            f'{_infobox_html(doc, cfg)}</div>')
+
+
+def _signature_html(doc: Document, cfg: Config) -> str:
+    if not doc.signature:
+        return ""
+    sig = cfg.letterhead.signature
+    name = sig.get("name", cfg.letterhead.name)
+    place = sig.get("place", cfg.letterhead.city)
+    return (
+        '<div class="signature">'
+        f'<div class="signature-place-date">{_esc(place)}, '
+        f'{doc.date.strftime(cfg.date_format)}</div>'
+        '<div class="signature-line"></div>'
+        f'<div class="signature-name">{_esc(name)}</div>'
+        f'<div class="signature-firm">{_firm_line(cfg.letterhead)}</div>'
+        '</div>')
+
+
+def render_document(cfg: Config, doc: Document) -> str:
+    theme = load_theme(cfg.theme, cfg.base)
+    color = (f":root {{ --primary-color: {cfg.color}; }}" if cfg.color else "")
+    body_html = markdown.markdown(doc.body_md, extensions=_MD_EXTENSIONS)
+    number = f' <span class="doc-number">{_esc(doc.number)}</span>' if doc.number else ""
+    return f"""<!DOCTYPE html>
+<html lang="{_esc(doc.lang or cfg.lang)}">
+<head>
+<meta charset="utf-8">
+<title>{_esc(doc.doc_type)}: {_esc(doc.title)}</title>
+<style>{theme}</style>
+<style>{color}</style>
+</head>
+<body>
+{_header_html(cfg.letterhead)}
+{_footer_html(cfg.letterhead, cfg.labels)}
+<table class="page">
+<thead><tr><td><div class="header-space"></div></td></tr></thead>
+<tbody><tr><td class="content">
+{_first_page_head(doc, cfg)}
+<div class="doc-head">
+<div class="doc-type">{_esc(doc.doc_type)}{number}</div>
+<h1 class="doc-title">{_esc(doc.title)}</h1>
+</div>
+<div class="doc-body">
+{body_html}
+</div>
+{_signature_html(doc, cfg)}
+</td></tr></tbody>
+<tfoot><tr><td><div class="footer-space"></div></td></tr></tfoot>
+</table>
+</body>
+</html>
+"""

praxigraph/themes/letter.css

@@ -0,0 +1,297 @@
+/* Theme "letter": A4 business letterhead in the style of a classic black
+ * invoice template (Roboto Condensed, black primary color, logo top right,
+ * four-column footer with the company data).
+ *
+ * Chrome headless has no support for CSS margin boxes or `position: running`,
+ * so the letterhead uses the two mechanisms Chrome's print engine does honor:
+ * `position: fixed` elements repeat on every printed page, and a table's
+ * thead/tfoot repeat as well and reserve the vertical space for them.
+ */
+
+@import url('https://fonts.googleapis.com/css2?family=Roboto+Condensed:ital,wght@0,100..900;1,100..900&display=swap');
+
+:root {
+    --primary-color: #000000;
+    --muted-color: #666666;
+    --rule-color: #000000;
+    --page-left: 20mm;
+    --page-right: 15mm;
+    --header-height: 46mm;
+    --footer-height: 30mm;
+}
+
+@page {
+    size: A4 portrait;
+    margin: 0;
+}
+
+* { box-sizing: border-box; }
+
+body {
+    margin: 0;
+    font-family: "Roboto Condensed", "Helvetica Neue", Arial, sans-serif;
+    font-size: 9pt;
+    line-height: 11.5pt;
+    color: #000;
+}
+
+/* Page skeleton: thead/tfoot spacers reserve the letterhead zones. */
+table.page {
+    width: 100%;
+    border-collapse: collapse;
+    border-spacing: 0;
+}
+
+table.page > thead > tr > td,
+table.page > tfoot > tr > td {
+    padding: 0;
+}
+
+.header-space { height: var(--header-height); }
+.footer-space { height: var(--footer-height); }
+
+td.content {
+    padding: 0 var(--page-right) 0 var(--page-left);
+    vertical-align: top;
+}
+
+/* Letterhead header: repeated on every page via position: fixed. */
+header.letterhead-header {
+    position: fixed;
+    top: 0;
+    left: var(--page-left);
+    right: var(--page-right);
+    height: var(--header-height);
+}
+
+header.letterhead-header .logo,
+header.letterhead-header .logo svg,
+header.letterhead-header .logo img {
+    position: absolute;
+    top: 9mm;
+    right: 0;
+    width: 27mm;
+    height: 27mm;
+    object-fit: contain;
+}
+
+header.letterhead-header .logo svg,
+header.letterhead-header .logo img {
+    top: 0;
+    right: 0;
+}
+
+header.letterhead-header .logo-fallback {
+    position: absolute;
+    top: 12mm;
+    right: 0;
+    font-size: 16pt;
+    font-weight: 400;
+    color: var(--primary-color);
+    text-align: right;
+}
+
+/* Letterhead footer: four-column company grid, repeated on every page. */
+footer.letterhead-footer {
+    position: fixed;
+    bottom: 0;
+    left: var(--page-left);
+    right: var(--page-right);
+    height: var(--footer-height);
+    font-size: 7pt;
+    line-height: 10pt;
+    color: var(--primary-color);
+}
+
+footer.letterhead-footer .footer-grid {
+    position: absolute;
+    bottom: 8mm;
+    left: 0;
+    right: 0;
+    display: grid;
+    grid-template-columns: repeat(4, 1fr);
+    column-gap: 2mm;
+}
+
+footer.letterhead-footer .footer-label {
+    display: inline-block;
+    margin-right: 1mm;
+}
+
+/* E-mail and website are clickable in the PDF, but look like plain text. */
+footer.letterhead-footer a {
+    color: inherit;
+    text-decoration: none;
+}
+
+/* First page: sender line + recipient on the left, info box on the right. */
+.first-page-head {
+    display: flex;
+    justify-content: space-between;
+    gap: 10mm;
+    margin-bottom: 10mm;
+}
+
+.first-page-head.with-recipient { min-height: 45mm; }
+
+.recipient-block { max-width: 85mm; }
+
+.addressline {
+    font-size: 7pt;
+    line-height: 9pt;
+    margin-bottom: 6mm;
+}
+
+.recipient {
+    font-size: 9pt;
+    line-height: 1.35;
+}
+
+.infobox { width: 65mm; flex: 0 0 65mm; }
+
+.infobox table {
+    width: 100%;
+    border-spacing: 0;
+    font-size: 7pt;
+}
+
+.infobox td {
+    padding: 0.5mm;
+    vertical-align: top;
+    word-wrap: anywhere;
+}
+
+.infobox td.infobox-label { padding-left: 0; }
+.infobox td.infobox-value { text-align: right; }
+
+/* Document heading */
+.doc-head { margin-bottom: 5mm; }
+
+.doc-type {
+    font-size: 9pt;
+    letter-spacing: 0.15em;
+    text-transform: uppercase;
+    color: var(--muted-color);
+    margin-bottom: 1.5mm;
+}
+
+.doc-type .doc-number { color: var(--muted-color); }
+
+h1.doc-title {
+    font-size: 14pt;
+    line-height: 17pt;
+    font-weight: 700;
+    color: var(--primary-color);
+    margin: 0;
+}
+
+/* Body typography (rendered from Markdown) */
+.doc-body h2 {
+    font-size: 11pt;
+    line-height: 14pt;
+    font-weight: 700;
+    margin: 6mm 0 2mm;
+    page-break-after: avoid;
+}
+
+.doc-body h3 {
+    font-size: 9.5pt;
+    font-weight: 700;
+    margin: 4mm 0 1.5mm;
+    page-break-after: avoid;
+}
+
+.doc-body h4 {
+    font-size: 9pt;
+    font-weight: 700;
+    margin: 3mm 0 1mm;
+    page-break-after: avoid;
+}
+
+.doc-body p { margin: 0 0 2.5mm; }
+
+.doc-body ul, .doc-body ol {
+    margin: 0 0 2.5mm;
+    padding-left: 5mm;
+}
+
+.doc-body li { margin-bottom: 1mm; }
+
+.doc-body a { color: inherit; }
+
+.doc-body hr {
+    border: none;
+    border-top: 0.5pt solid var(--muted-color);
+    margin: 4mm 0;
+}
+
+.doc-body blockquote {
+    margin: 0 0 2.5mm;
+    padding: 1mm 0 1mm 3mm;
+    border-left: 1.5pt solid var(--rule-color);
+    color: #333;
+}
+
+.doc-body code {
+    font-family: "SF Mono", "Consolas", "Liberation Mono", monospace;
+    font-size: 8pt;
+    background: #f2f2f2;
+    padding: 0 1mm;
+}
+
+.doc-body pre {
+    background: #f2f2f2;
+    padding: 2mm;
+    margin: 0 0 2.5mm;
+    overflow-wrap: anywhere;
+    white-space: pre-wrap;
+    page-break-inside: avoid;
+}
+
+.doc-body pre code { background: none; padding: 0; }
+
+/* Tables in the invoice style: black header row, thin rules between rows. */
+.doc-body table {
+    border-collapse: collapse;
+    width: 100%;
+    margin: 3mm 0 4mm;
+    font-variant-numeric: tabular-nums;
+    font-feature-settings: "tnum" 1;
+}
+
+.doc-body table th {
+    background: var(--primary-color);
+    color: #fff;
+    font-weight: 700;
+    text-align: left;
+    padding: 1.5mm 1mm;
+}
+
+.doc-body table td {
+    padding: 1.5mm 1mm;
+    vertical-align: top;
+    border-bottom: 0.5pt solid #999;
+}
+
+.doc-body table tr { page-break-inside: avoid; }
+
+/* Signature block */
+.signature {
+    margin-top: 14mm;
+    page-break-inside: avoid;
+}
+
+.signature-place-date { margin-bottom: 14mm; }
+
+.signature-line {
+    width: 60mm;
+    border-top: 0.5pt solid #000;
+    margin-bottom: 1mm;
+}
+
+.signature-name { font-weight: 700; }
+
+.signature-firm {
+    font-size: 7pt;
+    color: var(--muted-color);
+}

praxigraph-1.0.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.5
+Name: praxigraph
+Version: 1.0.0
+Summary: Markdown-driven business document generator on your own letterhead: reports, minutes and certificates as PDF via Chrome headless
+Project-URL: Homepage, https://github.com/Supportlik/Praxigraph
+Project-URL: Repository, https://github.com/Supportlik/Praxigraph
+Project-URL: Issues, https://github.com/Supportlik/Praxigraph/issues
+Project-URL: Changelog, https://github.com/Supportlik/Praxigraph/blob/main/CHANGELOG.md
+Project-URL: Specification, https://github.com/Supportlik/Praxigraph/blob/main/docs/SPEC.md
+Author-email: Michael Bortlik <michael@bortlik.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: generator,letterhead,markdown,minutes,pdf,protocol,report
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Office/Business
+Classifier: Topic :: Printing
+Classifier: Topic :: Text Processing :: Markup :: HTML
+Requires-Python: >=3.10
+Requires-Dist: markdown>=3.5
+Requires-Dist: pypdf>=6.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# Praxigraph
+
+[![CI](https://github.com/Supportlik/Praxigraph/actions/workflows/ci.yml/badge.svg)](https://github.com/Supportlik/Praxigraph/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/praxigraph.svg)](https://pypi.org/project/praxigraph/)
+[![Python versions](https://img.shields.io/pypi/pyversions/praxigraph.svg)](https://pypi.org/project/praxigraph/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/Supportlik/Praxigraph/blob/main/LICENSE)
+
+**Praxigraph** (Greek *πρᾶξις* "act, transaction, proceeding" + *γράφειν* "to write": "the one that writes down your proceedings") is a Markdown-driven generator for business documents on your own letterhead: **meeting minutes, status reports, certificates, timesheets** — anything you issue on company paper that is not an invoice. It is the sibling project of [Ergograph](https://github.com/Supportlik/Ergograph), which does the same for CVs and dossiers.
+
+The generator contains **no personal data**. Your letterhead (company name, address, contact, tax IDs, bank details, logo) lives in a `config.yaml` outside the repo; each document is one Markdown file with YAML front matter. The code only provides rendering, the theme and the PDF export.
+
+## How it works
+
+```
+config.yaml + documents/*.md  ->  HTML (theme "letter")  ->  PDF (Chrome headless)
+```
+
+1. `config.yaml` holds the letterhead and steers the build: header logo and the multi-column footer (address, contact, tax IDs, bank) are printed on **every** page.
+2. One Markdown file per document. The front matter carries the document type, title, date, an optional number, recipient and extra info-box rows; the Markdown body becomes the content — headings, lists and tables included.
+3. Chrome (headless) renders the HTML to A4 PDFs, which then get page numbers (`i / n`, bottom right) and title/author metadata stamped in.
+
+## Installation
+
+Requirements: Python ≥ 3.10 and Google Chrome or Chromium. Chrome is only needed
+for the PDF step (`praxigraph build --html-only` works without it) and is not
+installed by pip — Praxigraph looks for an existing installation (see `chrome:` below).
+
+```bash
+# as an isolated tool (recommended)
+uv tool install praxigraph
+
+# or into the current environment
+pip install praxigraph
+```
+
+All three dependencies (PyYAML, Markdown, pypdf) are pure Python.
+
+## Quick start
+
+```bash
+cd examples/minimal/
+praxigraph validate            # check config + documents
+praxigraph build               # build everything (HTML + PDF)
+praxigraph build --html-only   # HTML only, no Chrome
+praxigraph build --doc kickoff-protokoll
+```
+
+The PDFs end up under `pdf/YYYY-MM-DD_<slug>.pdf` — the date comes from the
+document's front matter, so rebuilding never shuffles your archive
+(disable the prefix with `output.date_prefix: false`).
+
+## Example output
+
+The rendered example PDFs are committed under
+[`examples/minimal/pdf/`](examples/minimal/pdf/): meeting minutes with a
+recipient address, a status report, and a signed timesheet certificate — all
+for a fictional company.
+
+## The steering file `config.yaml`
+
+```yaml
+letterhead:
+  name: Daniel Falkner                  # bold first line, also the PDF author
+  tagline: IT-Beratung & Systemintegration
+  street: Ahornweg 12
+  zip: "93049"
+  city: Regensburg
+  # country: Deutschland                # optional, shown in the footer
+  logo: assets/logo.svg                 # optional; SVG is inlined, PNG/JPEG embedded
+  contact:                              # optional; each key is optional too
+    phone: +49 941 000000
+    email: mail@falkner-it.example
+    website: falkner-it.example
+  tax:                                  # optional: vat_id, tax_number
+    vat_id: DE999999999
+  bank:                                 # optional: name, iban, bic
+    name: Musterbank
+    iban: DE02 1203 0000 0000 2020 51
+    bic: BYLADEM1001
+  signature:                            # used by documents with `signature: true`
+    name: Daniel Falkner
+    place: Regensburg
+
+theme: letter          # bundled theme, or path to your own .css
+# color: "#1a3c6e"     # accent color (title, footer); default black
+# lang: de             # HTML language attribute, default de
+# date_format: "%d.%m.%Y"
+
+documents: documents   # a directory with *.md, or an explicit list of files
+
+labels:                # optional overrides of the German defaults, e.g. for English paper
+  # date: Date
+  # vat_id: VAT ID
+
+output:
+  html_dir: .build/html
+  pdf_dir: pdf
+  date_prefix: true    # date-stamped file names; false = stable names
+
+# chrome: /path/to/chrome   # optional; otherwise auto-detected
+```
+
+The letterhead footer renders up to four columns, and empty ones simply
+disappear: address · contact · tax IDs · bank details.
+
+## A document
+
+````markdown
+---
+type: Protokoll                  # document type, printed above the title
+title: Kickoff Website-Relaunch
+date: 2026-08-14                 # also the file-name prefix
+number: P-2026-001               # optional, shown in the type line and info box
+recipient: |                     # optional; adds a DIN-letter address block
+  Muster GmbH
+  Frau Erika Muster
+  Musterallee 8
+  93047 Regensburg
+meta:                            # optional extra rows in the info box
+  - label: Projekt
+    value: Website-Relaunch
+signature: true                  # optional signature block (place, date, line, name)
+# slug: kickoff                  # optional, default: file name stem
+# lang: de                       # optional, overrides config
+---
+
+## Teilnehmer
+
+- Erika Muster (Muster GmbH)
+...
+````
+
+The body is standard Markdown (Python-Markdown with the `tables`,
+`fenced_code` and `sane_lists` extensions). Tables render in the letterhead
+style: dark header row, thin rules. Front matter values are plain text and are
+HTML-escaped; formatting belongs in the Markdown body.
+
+## Development
+
+```bash
+uv run pytest                        # test suite, no Chrome and no network needed
+cd examples/minimal && uv run praxigraph build
+```
+
+Design decisions and requirements live in [`docs/SPEC.md`](docs/SPEC.md).
+Version history: [`CHANGELOG.md`](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE)

praxigraph-1.0.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+praxigraph/__init__.py,sha256=qhwn9JVzn7ad4JHpqN4KWdEIEdSZ6MOw7I3cuZ8zyU8,100
+praxigraph/builder.py,sha256=tLpO6NOlN4RSwNYGkgAZLkR0cSF0UONdr1jTLyUZQnM,2624
+praxigraph/cli.py,sha256=LovditRnwDwavnigwysP9yCy5nHE2vcr_zfIxXWuXUI,2207
+praxigraph/config.py,sha256=vHaRxGK4x5dyY6-png-IzKckwttOG5iG9SsQ0F-ouWk,5325
+praxigraph/document.py,sha256=OBtiP7Yn_04Ky3ixBsCNNktvLZOtzBkLhhDxhihRho4,3150
+praxigraph/pdf.py,sha256=StC30V4y-Z30wo5ogGtKFLwlymLCF5XAe94emzTnHZs,4598
+praxigraph/render.py,sha256=MgXk2pRu1BSyFPKIrCb4ynNWJ_ow6yTCe7hmJS5dHrE,6973
+praxigraph/themes/letter.css,sha256=qJIPKb40Civ03Pprz1jGZ4uN3v4-bRX2YvStbxg5KJE,6243
+praxigraph-1.0.0.dist-info/METADATA,sha256=Awk4LiAEgi6KJR9eZJolDgTd-UsYG3ggLppEp6pYSjU,7675
+praxigraph-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+praxigraph-1.0.0.dist-info/entry_points.txt,sha256=HyaHWm17309E2XMwq6pdAGP27LaNyS7osgHa5GlxYlw,51
+praxigraph-1.0.0.dist-info/licenses/LICENSE,sha256=0G76jpWAUx1S_m32OMs7urX5SWzFONxklcvwsQHh_F4,1072
+praxigraph-1.0.0.dist-info/RECORD,,

praxigraph-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

praxigraph-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+praxigraph = praxigraph.cli:main

praxigraph-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael Bortlik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.