iftypeset (pubstyle) — publication-quality typesetting pipeline

This project is a thin, deterministic runtime for turning Markdown into high‑quality HTML/PDF using:

• A machine‑readable rule registry (Chicago / Bringhurst pointers; paraphrased rules only)
• Typeset profiles (spec/profiles/*.yaml) that map typographic intent → render tokens
• Post‑render QA gates (spec/quality_gates.yaml) that fail builds when layout degrades

It is designed to be embedded into constrained workers (e.g. Forgejo PDF export with --network=none) and also run as a standalone CLI.

Status: working spec + seeded rule registry. See STATUS.md.

Constraints (non-negotiable)

• No bulk OCR/transcription of Chicago/Bringhurst into this repo (copyright).
• Rule records are paraphrases only, backed by pointers (e.g. CMOS18 §X.Y pNNN (scan pMMM)).
• Chicago OCR (when needed) must be ephemeral (extract just enough to locate pointers; do not store page text).
• Optional profile webtypography_nc is CC BY-NC 4.0 (non-commercial only). See docs/18-webtypography-nc.md.

Quickstart (current)

From ai-workspace/iftypeset/:

• (Optional) Install deps into a venv: python3 -m venv .venv && . .venv/bin/activate && python -m pip install -r requirements.txt
• Install the console entrypoint: python3 -m pip install -e .
• Validate spec + rebuild indexes: iftypeset validate-spec --spec spec --build-indexes
• One-shot CI pipeline (recommended): iftypeset run --input fixtures/sample.md --out out --profile web_pdf --degraded-ok
• Multi-doc run (directory or glob): iftypeset run --input fixtures --out out --profile web_pdf --degraded-ok
• Lint Markdown (emits out/lint-report.json + out/manual-checklist.md): iftypeset lint --input fixtures/sample.md --out out --profile web_pdf
• Lint with auto-fix + post-fix diagnostics: iftypeset lint --input fixtures/sample.md --out out --profile web_pdf --fix --fix-mode rewrite --lint-fixed
• Render HTML + CSS: iftypeset render-html --input fixtures/sample.md --out out --profile web_pdf
• Run QA gates (HTML fallback if no PDF): iftypeset qa --out out --profile web_pdf
• Render PDF (if an engine is installed): iftypeset render-pdf --input fixtures/sample.md --out out --profile web_pdf
• Coverage + trust contract + HTML index: iftypeset report --spec spec --out out (writes out/report/index.html)
• Environment/determinism report: iftypeset doctor --spec spec --out out
• Portable review bundle: iftypeset bundle --out out (writes out/iftypeset-bundle.tar.gz)
• Run self-check tests: python3 -m unittest discover -s tests -p 'test_*.py'
• Inspect profiles/gates/rules:
  • iftypeset profiles list
  • iftypeset gates show --profile web_pdf
  • iftypeset rules list --category links
  • iftypeset rules show HOUSE.LINKS.URLS.PREFER_HTTPS

If you do not want to install the console entrypoint, you can still run:

• PYTHONPATH=src python3 -m iftypeset.cli <command> ...

Config file (iftypeset.yaml)

You can set repo defaults in ./iftypeset.yaml. CLI flags always win.

Example:

defaults:
  spec: spec
  out: out
  profile: web_pdf
lint:
  fail_on: must
  degraded_ok: true
run:
  skip_pdf: false
  require_pdf: false
  engine: playwright

To use a different config path: iftypeset --config /path/to/iftypeset.yaml <command> ...

Enforcement limits (read this)

• Not all rules are automated. Manual rules (tagged manual_checklist=true) appear in out/manual-checklist.md.
• PDF QA is heuristic. It depends on text extraction and will miss some layout failures.
• Renderer variance exists. Profiles aim for determinism, but output still depends on the PDF engine + fonts.
• Trust contract is explicit. Run iftypeset report to generate out/trust-contract.md with current limits.

Lint suppression (explicit, auditable)

You can suppress specific rules in a document when needed:

• Inline directive (applies to the next non-empty line):
  • <!-- iftypeset:ignore CMOS.PUNCTUATION.PARENS_BRACKETS.BALANCE -->
• Front matter allowlist:
  • iftypeset_ignore: [CMOS.PUNCTUATION.PARENS_BRACKETS.BALANCE, LINK.WRAP.RISK]

Suppression works by rule id or diagnostic code and should be used sparingly.

Session resilience (avoid “lost work”)

If a chat/session resets, trust the repo, not the transcript:

• Quick resume: ./scripts/resume.sh
• Audit repo state: ./scripts/audit.sh
• Run CI sanity checks: ./scripts/ci.sh
• Create a portable restore point: ./scripts/checkpoint.sh "short note"

Details: docs/07-session-resilience.md Handoff snapshot: docs/08-handoff.md Project status: docs/09-project-status.md Downloadable summary: docs/11-project-summary.md Rendering pipeline: docs/17-rendering-pipeline.md Non-commercial WebTypography profile: docs/18-webtypography-nc.md Agent notes: AGENTS.md External review pack: docs/14-external-review.md Docker runtime: docs/15-docker.md

PDF renderers

render-pdf defaults to playwright and does not fall back silently.

• playwright (preferred; supports header/footer templates and avoids Chromium CLI “date/path” headers/footers)
• Optional (explicit --engine only): wkhtmltopdf, weasyprint

If no engine is present, the command exits with a clear message but still leaves HTML artifacts for QA.