Output & schema

Every parser normalizes its input into the same shape: a Markdown rendering for humans and a typed block schema for machines, plus extracted image assets.

Per-document output#

For each source file with slug <slug>, docparser writes:

data/parsed/<slug>/document.md     # human-readable Markdown
data/parsed/<slug>/document.json   # typed block schema
data/assets/<slug>/img-*.png       # extracted images

The JSON payload returned by the parse_* functions also carries a stats section summarizing what was captured:

payload = parse_path("paper.pdf", layout)
print(payload["stats"])

Block schema#

Across formats, content is decomposed into typed blocks so downstream RAG layers can rely on structure rather than re-parsing Markdown. Common block types include:

• heading — with the heading hierarchy carried as section_path.
• paragraph — body text.
• list — with list level preserved.
• table — structured rows/cells.
• image — with a stable asset name plus nearby_caption, context_before, and context_after.
• code — fenced code blocks (from Markdown input).

Format-specific metadata rides along too — for example .xlsx cells carry data_type, number_format, hyperlink, comment, and formula; OCR'd PDF blocks carry "ocr": true. See Supported formats.

Image naming#

Extracted images use a stable, content-addressed name:

img-<seq>-<sha10>.<ext>

The <sha10> (first 10 hex chars of the image SHA) keeps names stable across re-runs unless the image bytes change — which is also what makes VLM caption caching free on re-runs.

Corpus rollup#

run_all (and docparser parse-all) additionally write a corpus-level rollup across everything in data/raw/:

CORPUS.md                    # top-level Markdown index
data/parsed/corpus.json      # combined corpus JSON

Next#

See the full programmatic surface in the API reference.