docling-project / docling-project/docling
feat: add configurable image placeholder for chunking output
- 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
Assessment
This issue has not been assessed yet.