Skip to content

CLAUDE.md

Latest commit

 

History

History
57 lines (40 loc) · 1.8 KB

CLAUDE.md

File metadata and controls

57 lines (40 loc) · 1.8 KB

Kinscript - Claude Code Context

Project Overview

Kinscript converts genealogical markdown documents to PDFs via LaTeX. The main entry point is src/kinscript/cli.py which orchestrates:

  1. YAML frontmatter extraction
  2. Pandoc conversion (markdown → LaTeX)
  3. Lua filter processing (children tables, drop-caps)
  4. LaTeX post-processing (Python module)
  5. xelatex compilation (LaTeX → PDF)

The shell script kinscript.sh is a thin wrapper that calls the Python CLI via uv run kinscript.

Key Files

  • kinscript.sh - Main shell script entry point
  • src/kinscript/ - Python package
    • yaml_extract.py - YAML frontmatter parsing
    • latex_postprocess.py - LaTeX table formatting transforms
  • lua/kinscript_1.lua - Pandoc Lua filter for AST transforms
  • tex/template_kinscript_1.tex - LaTeX template
  • tests/ - pytest test suite

Development

Running Tests

uv run pytest

Python Module Calls

When calling Python modules from shell scripts, always use uv run:

# Correct
uv run python3 -m kinscript.yaml_extract "$file"

# Wrong - may fail if package not in system Python
python3 -m kinscript.yaml_extract "$file"

Architecture Notes

Children Tables

The children-table fenced divs in markdown are processed by the Lua filter. They use hanging indent paragraphs with \llap for column alignment rather than LaTeX table environments. This allows regular \footnote commands to work correctly (table environments require special \tablefootnote handling).

LaTeX Post-Processing

The Python module applies these transforms to generated .tex files:

  • Replace LINEBREAK placeholder with \\[6pt]
  • Fix minipage alignment ([b] → [c])
  • Wrap tables in tablebox environment
  • Replace booktabs rules with hlines
  • Format header text (uppercase, smaller font)