docling-project / docling-project/docling

feat: add configurable image placeholder for chunking output

Open
#3,435 2 comments 0 reactions 0 assignees View on GitHub
enhancement triage/close-implemented
Dominant language
Python
Stars
66.4k
Forks
4.8k
Avg merge
2d 21h
Merged PRs (30d)
84

Description

### Requested feature

Add optional configuration fields to `docling.datamodel.service.chunking.BaseChunkerOptions`:

```python
image_placeholder: Optional[str] = None
use_markdown_images: bool = False
```

These options would allow controlling how image references are represented inside chunked output independently from document export behavior.

Currently, image markers inside chunks are implicitly tied to `image_export_mode` from `ConvertDocumentsOptions`. This couples chunking behavior with document export configuration (JSON/Markdown/HTML serialization), which makes the system less flexible.

### Problems this solves

* Chunking and export concerns are currently coupled
* Users cannot independently control image representation in chunks vs exported documents
* The placeholder used in chunk text is effectively fixed
* Markdown image rendering behavior cannot be configured at chunk level
* It is not possible to support use cases such as:

* embedded images in exported documents
* but no placeholders in chunk outputs
* markdown image references only in chunks
* custom image placeholder formats for retrieval pipelines

### Proposed behavior

* `use_markdown_images`

* `True` → insert markdown image references into chunks
* `False` → disable markdown image generation in chunks

* `image_placeholder`

* If provided → use it when inserting image markers in chunks
* If `None` → fallback to current/default behavior (no image placeholder)

These options should operate independently from `ConvertDocumentsOptions.image_export_mode`.

### Alternatives considered

* Keep using `image_export_mode` from `ConvertDocumentsOptions`

* ❌ couples export logic with chunking logic
* ❌ does not allow independent configuration of chunk-level representation
* ❌ makes chunk output dependent on serialization settings

* Hardcode different behaviors per export mode inside chunker

* ❌ reduces flexibility and maintainability
* ❌ makes future extensions (e.g. embedded images) harder to integrate cleanly
* ❌ introduces additional implicit behavior

---

Requested by geoHeil

Reference: [[docling-jobkit PR #141](https://github.com/docling-project/docling-jobkit/pull/141)]

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.