Skip to content

fix(html): keep the alt text of an image in a table cell - #4710

Open
Harshil26202 wants to merge 2 commits into
Unstructured-IO:mainfrom
Harshil26202:fix/html-table-cell-image-alt
Open

Harshil26202 wants to merge 2 commits into
Unstructured-IO:mainfrom
Harshil26202:fix/html-table-cell-image-alt

Conversation

@Harshil26202

@Harshil26202 Harshil26202 commented Nov 13, 2026 •

Copy link
Copy Markdown

Summary

An image inside a table cell adds nothing to the Table element, because a cell's text comes from itertext(), which skips <img>. A feature table that marks cells with check-mark images loses those values in both text and text_as_html:

partition_html(text=(
    "<table><tr><th>Feature</th><th>Supported</th></tr>"
    '<tr><td>Search</td><td><img src="check.png" alt="Yes"></td></tr></table>'
))[0]
# main:  text "Feature Supported Search", text_as_html ...<td>Search</td><td/>...
# here:  text "Feature Supported Search Yes", text_as_html ...<td>Search</td><td>Yes</td>...

A table whose cells hold only images is dropped on main, since its text is empty. partition_md is affected the same way, because Markdown such as | Search | ![Yes](check.png) | goes through the HTML partitioner.

The cell text is now gathered by a small walker that matches itertext() (comments and processing instructions still contribute only their tail) and adds each image's alt text where the image is. An image without alt still adds nothing.

Validation

  • New tests test_it_keeps_the_alt_text_of_an_image_in_a_table_cell (text and text_as_html, an image between words, an image without alt) and test_it_emits_a_Table_element_for_a_table_whose_cells_are_only_images. Both fail on main and pass here.
  • test_partition_html_on_ideas_page changes: the essay title on that page is an image, <img alt="How to Get New Ideas">, so the table text now starts with the title.
  • pytest test_unstructured/partition/html/ test_unstructured/partition/test_md.py: 505 passed. ruff check and ruff format --check are clean.
  • Partitioned all 19 HTML files under example-docs on main and on this branch: only ideas-page.html changes, by the title above.
  • The ingest fixtures for ideas-page.html under test_unstructured_ingest/expected-structured-output* (box, dropbox, gcs, SharePoint) will gain that title too. Those connector tests need secrets, so I couldn't regenerate them; they need the fixture update workflow.
  • How I found it: a text conservation check on random Markdown through partition_md, where every word of the input has to appear in the elements. On main, 10 to 11 of every 100 documents lost text, all from images in table cells. With this change, none of 300 do.

Release note

Tables now include the alt text of images in their cells, in both text and metadata.text_as_html, and a table whose cells hold only images with alt text is now emitted. For documents with such tables the table text changes, so its element ID changes, chunk boundaries around it can shift, and a newly emitted table can shift the position-based IDs of the elements after it. Images without alt text, and tables without images, are unchanged.

Checklist

  • The PR title is a user-facing release-note entry with a conventional commit prefix.
  • Apply a category label (enhancement, bug, or an appropriate existing label), or ask a maintainer to apply it. (I can't apply labels; this is a bug.)
  • For breaking changes, use ! in the title and explain impact and migration above. (Not a breaking change.)

AI disclosure: this was found and fixed with Claude Code, which wrote the conservation check, traced the loss to the table cell text and drafted the fix and tests.

A table cell's text came from itertext(), which skips an <img>, so an
image in a cell contributed nothing to the Table text or text_as_html. A
feature table that marks cells with check-mark images such as
<img alt="Yes"> lost those values, and a table whose cells held only
images was dropped.

Cell text now includes each image's alt text in document order. The
ideas-page.html example, whose title is an image, now starts with that
title.

@cragwolfe cragwolfe left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Static review of 8d90377e5bb5a67a56b0a6405984e050a5d4a359: I found no actionable Critical, High, or Medium correctness issue in the change.

Maintainer decision required: This intentionally changes public extraction results. Image alternatives now contribute to table text and text_as_html, including captions, and a previously omitted image-only table can be emitted. As a result, table and later sequence-based element IDs can change; chunk boundaries, chunk counts, and surrounding text grouping can also change. Markdown tables can be affected through the HTML partitioner. Consumers that persist outputs or reconcile by ID may need to account for these changes. Please decide whether the project's release policy accepts these consequences for this fix and what communication or migration guidance is appropriate.

The traversal preserves image tails and escapes the reconstructed HTML. Missing or blank alternatives do not make an otherwise empty table emit. No application tests or reproductions were run as part of this static review; CI status is separate.

(authored by codex)

@Harshil26202

Copy link
Copy Markdown
Author

Thanks for the review. I added a Release note section to the description that spells out the visible changes: tables with image alt text get that text in text and text_as_html, their element IDs and nearby chunk boundaries can change, and image-only tables with alt text are now emitted. Tables without images are unchanged, as the 19 example HTML documents show (only ideas-page.html changes).

The HTML part of email-no-utf8-2014-03-17.111517.eml starts its table
with the Google logo, whose alt text is "Google Accounts". The table text
now includes it, which is the change this PR makes.
@Harshil26202

Harshil26202 commented Nov 21, 2026 •

Copy link
Copy Markdown
Author

Thanks for the approval. CI showed one test that this change affects, which I had missed: test_partition_email_partitions_an_html_part_with_quoted_printable_encoded_ISO_8859_1_charset. The table in that email starts with the Google logo, <img alt="Google Accounts">, so its text now starts with "Google Accounts Slava Gxyzxyz Hi Slava, ...". That is the alt text this PR keeps, so I updated the expected text in 12e4d55.

The other red checks were the runner's apt step failing (Process completed with exit code 100 in the runtime comparison job) and the jobs cancelled after the first failure; apart from that one email test, the 5611 other unit tests passed.

The branch is behind main; using "Update branch" is fine on my side.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants