Skip to main content

​
Overview

When page_chunks=True is passed to to_markdown() or to_text(), the return value is a list of dictionaries — one per page — rather than a single concatenated string. Each dictionary follows the schema described on this page. PyMuPDF4LLM Chunk Schema Diagram

​
Iterating over chunks

To quickly see the structure of each chunk, you can iterate over the list and print the keys of each dictionary: 
chunks = pymupdf4llm.to_markdown("document.pdf", page_chunks=True)
 
for chunk in chunks:
    for key in chunk:
        print(key)
        print("----")
        print (chunk[key])

​
Why use page chunks?

Page chunking is the recommended approach for any pipeline that needs to process, search, or embed a PDF’s content — rather than working with one giant string, you get a structured list where each page is a self-contained unit carrying both its text and the metadata needed to make that text useful. This matters most in RAG applications, where you need to attach source information (file path, page number, document title) to every embedded chunk so that retrieved passages can be traced back to their origin. The layout data in page_boxes adds another layer of utility — you can filter out headers, footers, and captions before embedding, or treat tables and body text differently depending on your retrieval strategy. Rather than post-processing a flat markdown string and trying to guess where page boundaries or section headings fall, chunking gives you that structure for free, directly from the PDF’s own layout engine. Example: Extracting page numbers and first 100 characters of text from each chunk 
import pymupdf4llm
 
chunks = pymupdf4llm.to_markdown("document.pdf", page_chunks=True)
 
for chunk in chunks:
    print(chunk["metadata"]["page_number"], chunk["text"][:100])
This is the recommended approach for RAG pipelines, as it lets you attach rich metadata to each piece of content before embedding or indexing it.

​
Chunk schema

Each item in the returned list is a dictionary with four top-level keys: 
{
    "metadata":   { ... },   # Document and page-level info
    "toc_items":  [ ... ],   # Table of contents entries for this page
    "page_boxes": [ ... ],   # Layout elements detected on this page
    "text":       "..."      # Full markdown text for this page
}

​
metadata

Contains both document-level properties (consistent across all chunks) and page-level properties (unique per chunk). 
chunk["metadata"] = {
    # Document-level
    "format":       "PDF 1.7",
    "title":        "My Document",
    "author":       "Jane Smith",
    "subject":      "",
    "keywords":     "",
    "creator":      "pdf-lib",
    "producer":     "pdf-lib",
    "creationDate": "D:20260206183204Z",
    "modDate":      "D:20260206183204Z",
    "trapped":      "",
    "encryption":   None,

    # Page-level
    "file_path":    "document.pdf",
    "page_count":   19,
    "page_number":  1        # 1-based
}
​
format
string
The PDF version string, e.g. "PDF 1.7".
​
title
string
Document title from PDF metadata. Empty string if not set.
​
author
string
Document author from PDF metadata. Empty string if not set.
​
creator
string
The application that originally created the PDF.
​
producer
string
The application that produced or converted the PDF.
​
creationDate
string
PDF date string in D:YYYYMMDDHHmmSSZ format.
​
modDate
string
Date the PDF was last modified, same format as creationDate.
​
encryption
string | None
Encryption method if the document is encrypted, otherwise None.
​
file_path
string
The file path of the source document as provided to to_markdown().
​
page_count
integer
Total number of pages in the document.
​
page_number
integer
The 1-based page number this chunk represents.

​
Usage example

for chunk in chunks:
    meta = chunk["metadata"]
    print(f"Page {meta['page_number']} of {meta['page_count']} — {meta['file_path']}")

​
toc_items

A list of Table of Contents entries that fall on this page. Each entry is a list in the format [level, title, page_number]. 
chunk["toc_items"] = [
    [1, "Introduction",        3],
    [2, "Background",          3],
    [2, "Problem Statement",   3],
]
​
level
integer
Heading hierarchy depth. 1 = top-level chapter, 2 = section, 3 = subsection, etc.
​
title
string
The heading text as it appears in the Table of Contents.
​
page_number
integer
The page number the TOC entry points to (1-based).
toc_items is an empty list [] for pages that have no TOC entries, or for documents without a Table of Contents. Always check before iterating.

​
Usage example

for chunk in chunks:
    for level, title, page in chunk["toc_items"]:
        indent = "  " * (level - 1)
        print(f"{indent}{title} (p.{page})")

​
page_boxes

A list of layout elements detected on the page by the layout analysis engine. Each element describes a discrete visual block — a paragraph, heading, image, table, list item, and so on — along with its position on the page. 
chunk["page_boxes"] = [
    {
        "index": 0,
        "class": "section-header",
        "bbox":  (58, 55, 560, 108),
        "pos":   (0, 88)
    },
    {
        "index": 1,
        "class": "text",
        "bbox":  (36, 125, 574, 209),
        "pos":   (88, 524)
    },
    ...
]
​
index
integer
Zero-based position of this box in the page’s layout order (reading order, top to bottom).
​
class
string
The type of layout element detected. See the box classes table below.
​
bbox
tuple[float, float, float, float]
Bounding box of the element in PDF page coordinates: (x0, y0, x1, y1). Origin is the top-left of the page. Units are PDF points (1 point = 1/72 inch).
​
pos
tuple[int, int]
Character offsets into the page’s text string: (start, end). Use these to slice the exact text that corresponds to this layout element.
Box classes
ClassDescription
textBody paragraph or general prose
section-headerA heading or section title
list-itemA bullet or numbered list entry
tableA detected table
pictureAn image or figure
captionA caption beneath a figure or table
page-footerFooter content at the bottom of the page
page-headerHeader content at the top of the page

​
Usage example — extract only headings

for chunk in chunks:
    boxes = chunk["page_boxes"]
    text  = chunk["text"]

    for box in boxes:
        if box["class"] == "section-header":
            start, end = box["pos"]
            heading_text = text[start:end].strip()
            print(heading_text)

​
Usage example — get bounding boxes for all images

for chunk in chunks:
    page = chunk["metadata"]["page_number"]
    for box in chunk["page_boxes"]:
        if box["class"] == "picture":
            print(f"Page {page}: image at {box['bbox']}")

​
text

The full markdown-formatted text content of the page as a single string. Headings, bold text, tables, and list items are represented using standard markdown syntax. 
chunk["text"] = """## Introduction

We highlight four promising research opportunities to improve
_Large Language Model_ inference for datacenter AI...

## **BACKGROUND**

...
"""
​
text
string
Markdown string for the entire page. Newlines separate logical blocks. Images that cannot be extracted are replaced with a placeholder like ==> picture [535 x 193] intentionally omitted <==.
The character offsets in each page_boxes[n]["pos"] correspond directly to positions within this string, so you can use them to precisely extract the text for any layout element.

​
Usage example — slice text by layout element

chunk = chunks[0]
text  = chunk["text"]

for box in chunk["page_boxes"]:
    start, end = box["pos"]
    print(f"[{box['class']}]", text[start:end].strip()[:80])

​
Full iteration example

import pymupdf4llm

chunks = pymupdf4llm.to_markdown("document.pdf", page_chunks=True)

for chunk in chunks:
    meta      = chunk["metadata"]
    toc       = chunk["toc_items"]
    boxes     = chunk["page_boxes"]
    text      = chunk["text"]

    print(f"\n--- Page {meta['page_number']} of {meta['page_count']} ---")

    # TOC entries on this page
    for level, title, page in toc:
        print(f"  TOC [{level}]: {title}")

    # Layout elements
    for box in boxes:
        start, end = box["pos"]
        snippet = text[start:end].strip()[:60].replace("\n", " ")
        print(f"  [{box['class']}] {snippet}")
MethodDescription
to_markdown()The method that produces chunks when page_chunks=True
to_json()Alternative export with full bounding box and layout data
get_key_values()Extract form field data from a PDF

JSON Schema

The JSON schema reference for the full output of to_json(), including text, image, table, and drawing blocks with bounding boxes and metadata.

Extract JSON Guide

Working walkthrough with filtering, DataFrame export, and pipeline examples.

to_json()

Full API reference for to_json().

Get Form Data

Extracting form data from PDF as key value pairs.