How the paginate_output Option in Chandra Formats Multi-Page Document Outputs

The paginate_output option inserts visual page separators between OCR results when merging multi-page documents into Markdown and HTML outputs.

The paginate_output flag controls how the Chandra OCR toolkit combines per-page recognition results when processing multi-page documents. When enabled, this option adds distinct visual markers between pages in the merged output files, transforming continuous text into clearly delineated sections. According to the datalab-to/chandra source code, this behavior is implemented in the CLI helper functions and affects both Markdown and HTML generation.

Where paginate_output Is Defined in the Chandra CLI

The --paginate_output flag is defined in chandra/scripts/cli.py at lines 78-82, where it is added as a boolean argument to the command-line interface. When users invoke the Chandra CLI, this flag is captured and passed directly to the save_merged_output function (lines 75-83 in the same file), which handles the final assembly of processed pages.

How Pagination Affects Markdown and HTML Output

Inside save_merged_output, the function iterates over per-page results returned by the OCR engine. For every page after the first (where page_num > 0), the code checks the paginate_output boolean before inserting separators between content blocks.

Markdown Page Separators

When paginate_output is True, Chandra inserts a Markdown horizontal rule variant between pages. The code appends:

f"\n\n{page_num}" + "-" * 48 + "\n\n"

This generates a line containing the page number followed by 48 dashes, creating a clear visual break like 1------------------------------------------------.

HTML Comment Separators

For HTML output, the function inserts semantic HTML comments indicating page boundaries:

f"\n\n<!-- Page {page_num + 1} -->\n\n"

This results in markers like <!-- Page 2 --> that are visible in source code but hidden when rendered in browsers.

Practical Usage Examples

You can enable pagination through both the command-line interface and the Python API.

Command Line Usage

Enable pagination when processing PDFs via the CLI:

chandra input.pdf output_dir --method vllm --paginate_output

Python API Usage

When calling the helper function directly in Python, pass the boolean flag to save_merged_output:

from pathlib import Path
from chandra.scripts.cli import save_merged_output

# results is a list of per-page inference results returned by the model

save_merged_output(
    output_dir=Path("output_dir"),
    file_name="example.pdf",
    results=results,
    save_images=True,
    save_html=True,
    paginate_output=True,  # enables the page separators

)

The result objects containing markdown and html fields are defined in chandra/model/schema.py, which structures the data that save_merged_output concatenates.

Summary

• The paginate_output option adds visual separators between pages in multi-page OCR outputs
• Markdown output receives page-numbered dash separators (48 dashes per the implementation in chandra/scripts/cli.py)
• HTML output receives comment markers (<!-- Page N -->) between pages
• The logic resides in the save_merged_output function within chandra/scripts/cli.py
• Without this flag, all pages are concatenated without delimiters into continuous documents

Frequently Asked Questions

What happens if I omit the --paginate_output flag?

If the flag is omitted or set to False, Chandra concatenates all page results into continuous text streams without any visual delimiters. This produces single uninterrupted Markdown and HTML files where content from page one flows directly into page two.

Can I customize the page separator format?

No, the separator format is hardcoded in the save_merged_output function at lines 78-82 of chandra/scripts/cli.py. The Markdown separator always uses exactly 48 dashes preceded by the page number, and HTML always uses standard comment tags.

Does paginate_output affect image generation?

No, the paginate_output flag only affects text-based outputs (Markdown and HTML). According to the source code in chandra/scripts/cli.py, image saving is controlled separately by the save_images parameter and is not modified by pagination logic.

Where is the pagination logic implemented?

The pagination logic is implemented in the save_merged_output function located in chandra/scripts/cli.py. This function processes result objects defined in chandra/model/schema.py and applies the separator logic when assembling the final merged documents.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}