Optional HTML field on RAG chunk records

[mvanhorn]

feat: optional HTML field on RAG chunk records

Motivation

Docling already converts to a structured DoclingDocument and exports retrieval chunks as JSONL via --to chunks. Each ChunkedDocumentResultItem carries text, raw_text, headings, captions, doc_items, page_numbers, and metadata (including origin). It does not carry the HTML of the items in that chunk.

Marker's --output_format chunks puts full HTML on each flat block so a RAG ingest job does not have to walk a tree. Users who want HTML tables (rowspan/colspan) currently run a second --to html export and try to join it to chunks themselves. docs/concepts/serialization.md already notes that HTML keeps table structure that Markdown flattens.

This is a small, default-off field on the existing chunk record, filled by HTMLDocSerializer over that chunk's doc_items. The serializer is already imported in docling/cli/main.py. docs/examples/trivial_chunking.py already serializes per item.

This feature was proposed from code analysis without any hands-on usage.

Research Summary

General Project Dogfooding (Phase 0.5 Step 1e / Phase 1b.5)

• Installed and ran project: NO
• Score: 0/10
• Screenshots: none
• Key observations: bulk skip. Clone inspected at 890dd42.

Feature-Specific Validation (Phase 2d)

• Feature validated: HTML field on ChunkedDocumentResultItem
• Tests run: static read of CLI writer, response model, chunker options, trivial_chunking serializer call
• Key finding: ChunkedDocumentResultItem (docling/datamodel/service/responses.py:156-195) has no html. CLI writer (docling/cli/main.py:658-706) dumps model_dump(mode="json") with text/raw_text only. HTMLDocSerializer is imported at main.py:39-43. Per-item serialize lives at docs/examples/trivial_chunking.py:76-81. tests/test_cli.py covers doclang/dclx/latex/html, not chunks.

Project Context

• Stars: 66923 | Language: Python | License: MIT | Maintainers: @cau-git, @dolfim-ibm, @vagenas, @PeterStaar-IBM
• Philosophy: local, MIT, DoclingDocument as the structured IR for gen-AI (convert, extract, chunk, serve)

Related Issues & Community Signals

• No open or closed GitHub issue/PR matched html chunks jsonl serialize HTMLDocSerializer rag chunk html (PHASE_3A CLEAN).
• Ideas discussion #2897 is a provenance source union (audio/video), not chunk HTML.
• PROCESS_LEVEL is DISCUSSION_PREFERRED: raise an Ideas discussion before a feature PR (community CONTRIBUTING).

Social Search Results

Consumed from parent host_handoff. last30days was not run on this host. Path B was not taken.

• Reddit: 25 main-topic items. Demand used: RAG HTML quality and provenance, not competitor keyword collisions.
• X / YouTube: failed on parent (404 / timeout). TikTok searched; Marker name collision.
• Cross-platform: document versioning asked independently on r/LangChain (15 upvotes, 40 comments), r/Rag (5/12), r/LLMDevs (1/22).

Source	Evidence	Engagement
r/LLMDevs	"Is your RAG pipeline eating garbage HTML?"	1 upvote, 16 comments
r/LangChain	correctness of RAG source text	4 upvotes, 6 comments
r/LangChain	high-recall RAG without losing provenance	6 upvotes, 9 comments

Competitive Analysis

Marker (datalab-to/marker) --output_format chunks emits FlatBlockOutput with html, id, block_type, page, polygon, bbox, section_hierarchy. README: "full HTML of each block inside, so you don't need to crawl the tree. This enable flexible and easy chunking for RAG." Renderer: https://github.com/datalab-to/marker/blob/6ae38895/marker/renderers/chunk.py

Docling --to chunks already flattens to JSONL records with doc_items refs. The missing piece is the HTML payload Marker puts on each record. Full-document save_as_html exists and is a different export.

Maintainer Analysis

• @cau-git: extraction, pdfium, in-flight #4201 and #3457. Not the chunk HTML owner.
• @dolfim-ibm / @vagenas: core IR, serializers, chunking docs. Likely reviewers for this PR.
• @PeterStaar-IBM: models / product direction.

What Gets Merged vs Rejected

• Merged fast: conventional-commit scoped PRs (feat(cli):, feat(chunking):), tests + docs checklist, DCO -s.
• Rejected / delayed: unsigned DCO; feature PRs with no prior issue/Discussion; label code agent slop.

Proposed Solution

Add an optional html: str | None = None field on ChunkedDocumentResultItem. Default omitted / null so existing JSONL stays byte-compatible when the flag is off.

Add include_html: bool = False on BaseChunkerOptions (same shape as include_raw_text).

Add CLI --chunks-include-html (default false). When set, export_documents fills html by serializing the chunk's doc_items with HTMLDocSerializer.

Put the serialize loop in docling/utils/chunk_html.py so the CLI and any later serve path share one helper. Helper signature:

def html_for_chunk(doc: DoclingDocument, doc_items: list[DocItem]) -> str:
    ...

Implementation: construct HTMLDocSerializer(doc=doc) once per document (caller may pass a cached serializer), then for each item call ser.serialize(item=item) as trivial_chunking.py:81 does, concatenate non-empty ser_res.text. Do not wrap a fake mini-document. Do not change the existing text / raw_text fields.

Default off. No new OutputFormat. No change to Marker-incompatible fields (polygon, block_type).

Approach

1. docling/datamodel/service/responses.py (ChunkedDocumentResultItem, ~line 156)
   • Add optional html with Field description: HTML serialization of this chunk's doc_items, omitted unless requested.
2. docling/datamodel/service/chunking.py (BaseChunkerOptions, ~line 23)
   • Add include_html: bool = False with a description matching include_raw_text.
3. docling/utils/chunk_html.py (new)
   • SPDX header (MIT).
   • html_for_chunk(doc, items, *, serializer=None) -> str.
   • Empty items -> "".
   • Skip items whose serialize result is empty (same skip as trivial_chunking).
4. docling/cli/main.py
   • New typer option --chunks-include-html next to --chunks-tokenizer (~line 786-800).
   • Thread bool into export_documents (signature ~480, call site ~1733).
   • Inside the JSONL loop (~686-699): if flag, html=html_for_chunk(conv_res.document, doc_chunk.meta.doc_items).
   • Reuse one HTMLDocSerializer(doc=conv_res.document) per file, not per chunk.
5. Tests
   • tests/test_chunk_html.py (new): load docs/examples/data/normal_4pages.json or a tiny constructed DoclingDocument; assert helper returns a string containing a tag from a known item; empty items -> "".
   • tests/test_cli.py: add test_cli_exports_chunks mirroring test_cli_exports_latex (markdown source, --to chunks, read *.chunks.jsonl, parse first line). Default run: html is null/absent. Flag run: html is a non-empty string. Keep hybrid tokenizer cost down: --chunks-type hierarchical if hierarchical does not pull HuggingFace.
6. Docs
   • docs/concepts/chunking.md: one short subsection under Usage that --to chunks --chunks-include-html adds html on each JSONL record.
   • docs/examples/hybrid_chunking.ipynb: one cell showing the field when using CLI or constructing ChunkedDocumentResultItem.

Estimated scope: ~80-120 lines of implementation plus tests and a notebook cell. S.

Do not: change text contextualize; add HTML to HierarchicalChunker itself; wait on serve-side chunk assembly (CLI is the only ChunkedDocumentResultItem(...) constructor today; include_html on options is the serve hook).

Alternatives Considered

1. Full-document HTML plus client-side split. Rejected: that is --to html today. The Marker gap is per-chunk HTML so ingest does not walk a tree.
2. Put HTML only in metadata. Rejected: Marker and the CLI record already use first-class fields (text, raw_text). A first-class optional html matches that shape. metadata stays for origin.

---

Happy to follow maintainer guidance before any PR (CLA noted).