pdf Card

PDF Cards

A pdf card is a document whose text has been extracted — the rendered markdown is the card body, and the original bytes stay attached beside it. It is what bbx scan-import writes for a scanned PDF that already carries a text layer (a scanner's own OCR, or a born-digital PDF).

Where the bytes live

Everything is inside the card's own attach scope, so refs are attach/…:

attach/source.pdf (or whatever filename.ref names) — the original file, unmodified. Read this when the body is not enough: the exact layout, a signature, a stamp, a scan artifact.
attach/docling.json.gz (docling.ref) — the canonical extraction: layout, reading order, bounding boxes, table structure. Gzipped JSON. Read it only when you need structure the markdown body dropped (e.g. cell-level table data or where on the page something sits).
attach/text-layer.txt — the document's raw text layer, verbatim, as the file itself carries it (no layout analysis, no rewriting). Read it when you need the exact characters rather than the rendered body. Absent when the document carries no extractable text.
attach/page-001.webp, page-002.webp, … — newly rendered pages, in page order. Existing cards may use .avif instead; both formats remain readable. Use these when you want to look at a page.
attach/figure-001.webp, … — newly extracted figures/images. Existing cards may use .avif; the body references figures inline.

The attached source file is preserved byte-for-byte when pages and figures are generated again. Reanalysis may replace generated AVIF files with WebP files, and existing AVIF attachments do not need conversion just to use WebP for new output. A direct link to a generated image filename can become stale. For a durable page link, link to the PDF card with ?page=N (one-based page number), not directly to a generated page image. Read the attached original when you need its exact bytes or appearance; do not assume every vision provider accepts every attached image format directly.

Frontmatter

error — present when extraction failed. The original file is still attached and is the only asset; there is no docling JSON, no page renders, and the body is empty. Nothing is lost — re-run extraction with bbx pdf reanalyze <card> (add --force-ocr when the text layer itself is junk), or read the attached original directly, or set unusable: true if the file is unusable. A card with docling and no error was extracted; an empty body is then a valid result — it means the document had no readable text, not that something broke.
unusable: true — you judged the document unusable (corrupt, junk, empty scan).
format — the source document type, e.g. pdf. format: records what the file was, distinct from the card type itself.
filename — provenance for the original: ref into the attach scope, via (channel such as scan-import or scan-upload/<token>, at the import time, and optionally original — the document's own date when known, YYYY, YYYY-MM, or YYYY-MM-DD — and note, how or why in prose), and optionally original-name, mime-type, size.
docling — ref to the gzipped extraction JSON, plus the version of the extractor that produced it.
metadata — pages, title, author read from the document itself. Any of them may be missing; a scanner rarely sets title/author.
description — a short summary of what the document is. Deliberately empty at intake; fill it in when you process the card.

Body

The rendered markdown of the document — headings, paragraphs, and tables as markdown tables. Figures appear as inline image references into the attach scope. Treat it as a faithful-but-lossy view: it is the right thing to read, search, and quote, and the original plus the page renders are there when it is not enough.

The `contains:` field