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

> Learn how Chandra's paginate_output option formats multi-page documents. Insert visual page separators into Markdown and HTML outputs for clearer OCR results.

- Repository: [Datalab/chandra](https://github.com/datalab-to/chandra)
- Tags: how-to-guide
- Published: 2026-03-27

---

**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`](https://github.com/datalab-to/chandra/blob/main/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:

```python
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:

```python
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:

```bash
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`:

```python
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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/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`](https://github.com/datalab-to/chandra/blob/main/chandra/scripts/cli.py). This function processes result objects defined in [`chandra/model/schema.py`](https://github.com/datalab-to/chandra/blob/main/chandra/model/schema.py) and applies the separator logic when assembling the final merged documents.