Skip to content

馃悰 FIX: Preserve literal alt text in HTML images - #1214

Open
AryanRG wants to merge 1 commit into
executablebooks:masterfrom
AryanRG:fix/html-image-literal-alt
Open

AryanRG wants to merge 1 commit into
executablebooks:masterfrom
AryanRG:fix/html-image-literal-alt

Conversation

@AryanRG

@AryanRG AryanRG commented Oct 17, 2026 •

Copy link
Copy Markdown

Fixes #1213.

With html_image enabled, <img src="example.png" alt="A # sign"> currently produces alt text A and a warning. Decoded quotes can drop the alt attribute entirely, and embedded newlines can truncate it. HTML attributes are being serialized into directive option text and parsed a second time.

Pass the existing allowed attributes through run_directive(..., additional_options=...) instead. Directive option validation remains active. Trim width/height values to preserve the former dimension whitespace normalization, while preserving literal alt text, including its leading/trailing spaces.

Regression tests cover block and inline images, quotes, hash signs, embedded newlines, literal alt whitespace, padded numeric/unit/percentage dimensions, and invalid dimensions. The three-file change includes an Unreleased changelog entry.

Compatibility observation: the synthesized directive block_text and resulting standard image node's rawsource now become empty instead of containing generated :key: value lines. This was observed in a local probe. Custom image directives or downstream consumers that inspect those fields may observe a difference; compatibility with all such consumers has not been established.

This addresses HTML attribute conversion in html_to_nodes.py. #1210 / #1211 address a separate Markdown image token path in renderInlineAsText.

Validation on macOS with Python 3.11.16:

  • tox -e py311-sphinx8,py311-sphinx9 -- tests/test_html tests/test_docutils.py tests/test_renderers/test_parse_directives.py -q: 136 passed on each stack (Sphinx 8.2.3 / docutils 0.21.2 and Sphinx 9.0.4 / docutils 0.22.4).
  • tox -e py311-sphinx9 -- -q: 1,265 passed, 11 skipped; 22 existing BeautifulSoup findAll deprecation warnings in the Sphinx test helpers.
  • pre-commit run --all-files: all seven configured checks passed, including Ruff and mypy.
  • git diff --check: passed.
  • Before the production fixes, the original literal-alt regression had six failing cases on Sphinx 9; the subsequent padded-dimension regression had six failing cases on each of Sphinx 8 and 9.

Tox was invoked using uv tool run --from tox --with tox-uv tox. Sphinx 8 received the focused suites, not the full suite. Other Python/platform combinations, the separate docutils-only matrix, standalone documentation/LaTeX builds, and the 11 skipped tests were not exercised locally. Hosted CI results are separate from these local results.

AI assistance was used to prepare the implementation and regression tests.

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.

HTML image alt text is reparsed as directive option syntax

1 participant