thermal-print

Designing for the 58mm thermal printer

You are designing on a strip of paper: 384px wide (1 CSS px = 1 printer dot = 0.125mm), unlimited height, printed at 203dpi in pure 1-bit black & white.

Two paths — pick the right one

• Quick print (notes, lists, todos, plain receipts): call print_markdown. GFM + syntax-highlighted code fences, mermaid diagrams, LaTeX math ($...$ / $$...$$), task lists, tables, remote images — all supported. Three type-size tiers via size (see "Type size" below); default to medium.
• Custom design: write an HTML body fragment (no <html>/<head>), bring your own <style>, iterate with preview_html → print_html. HTML gives you full control of every font-size — set font-size in your own CSS (respect the ≥18px body / ≥20px CJK floors below).
• Continuous / log mode (typewriter-style: hourly logs, streaming notes): print_markdown with flow: "continuous". Zero top/bottom margins and no trailing feed, so chunks from separate calls join seamlessly into one strip. Rules: send one complete markdown block per call (a fenced code block, a list, a paragraph — never split mid-construct; incomplete chunks are rejected with an error instead of printed). Keep chunks short (1–5 lines), prefix log lines with a mono timestamp; size: "small" is acceptable here since logs are intentionally dense (otherwise prefer medium). The human presses the printer's FEED button after tearing — that IS the margin; no begin/end calls needed.

Workflow (always)

1. Write the content.
2. Preview — the returned image is the exact 1-bit output that will print. Check: nothing clipped at 384px, text legible, no accidental gray speckle.
3. Iterate, then print. Paper is physical — never print unpreviewed content.

Hard physical constraints

• 1-bit output. Photos/gradients are auto-detected and dithered (Atkinson default; algorithm: "jarvis" for smoother gradients, "bayer" for a halftone newspaper look). Text must be pure #000 on #fff — gray or colored text prints as speckle. Override detection with mode: "text"|"photo".
• Type size (print_markdown): three tiers — large (24px, headlines / very short notes), medium (19px) — the recommended default, use it for almost everything, small (14px, the minimum — ONLY for genuinely dense or long content; it's noticeably harder to read, so never default to it). When in doubt, medium.
• Floors: body ≥ 18px, fine print ≥ 16px absolute floor, CJK ≥ 20px (hardware cell is 24×24 dots). Line-height 1.3–1.4 body, 1.1–1.2 headings.
• Rules/borders ≥ 2px — 1px hairlines drop out. Dashed 2px = classic receipt.
• Give rows breathing room. Thermal dot-gain fattens everything ~1px, so tight vertical stacks bleed into each other. For icon/checkbox + text rows use display:flex; align-items:center; gap:8px; line-height:1.4 and ≥6px between rows — never absolutely-position a checkbox/icon column over the text column.
• Network works (remote images load) but every bundled font/icon below is local — prefer them.