Skip to content

Add accessible alt text for Docs equations - #69

Merged
Divide-By-0 merged 5 commits into
masterfrom
codex/docs-accessible-alt-text
Sep 19, 2026
Merged

Divide-By-0 merged 5 commits into
masterfrom
codex/docs-accessible-alt-text

Conversation

@Divide-By-0

@Divide-By-0 Divide-By-0 commented Aug 29, 2026 •

Copy link
Copy Markdown
Owner

Human intent

Make Google Docs equations accessible by default, with no extra setting. Use raw LaTeX as fallback alt text, automatically recognize custom descriptions, and explain support in the Google Sites FAQ.

What changed

  • Every rendered Docs equation gets raw-LaTeX alt text unless an immediately adjacent _{description} provides a custom description: $$x^2$$_{x squared}.
  • Removes the Advanced checkbox and saved preference. Existing false preferences and older sidebar arguments cannot disable descriptions.
  • Preserves balanced descriptions through single/all de-rendering, and leaves empty, malformed, or non-adjacent suffixes untouched. Custom metadata failures preserve source text; raw fallback remains best effort.
  • Both MathJax and server renderer paths share this behavior. CI runs all regression tests and builds both Docs and Slides sidebars.

Validation

  • npm test: 54 passing, including default-on scanning, raw fallback, custom metadata rollback, and single/all round trips.
  • Docs TypeScript build and sidebar build passed; git diff --check passed.
  • The updated default-on tests failed against the previous generated server code and passed after rebuilding the change.
  • Live Google Docs screenshots of the current always-on behavior, captured 2026-09-18 against this branch on the Docs project head: PR comment and tests/evidence/pr69. They cover Advanced Settings with no checkbox, the six fixtures rendered, Google's own Alt text panel for the raw fallback / an authored description / nested braces, and a De-render All round trip.
  • The earlier screenshots further down the comment thread show an alt-text checkbox that no longer exists; they predate the opt-in removal. The CodeCogs server-renderer pass in that same comment still stands.
  • This branch has been merged with master, so it carries the Inline-fragmentation fix from Fix inline MathJax equations losing terms #71; npm test is 159 passing.

Website FAQ

Published and verified the alt-text note at https://www.autolatex.com/faq. It labels automatic alt text as coming in the next Docs update until this PR is released. Existing FAQ text was preserved; Google Sites publish review listed only the FAQ page.

Release status

Docs Marketplace remains v95. This PR updates the upcoming Docs release; it does not change the already-published Slides v15.

@Divide-By-0

Copy link
Copy Markdown
Owner Author

Live Google Docs verification — all six cases passed

Tested PR head 6b47b8d0684f73d1bb1be67ac06a7337aa7f883a in the user-provided bound Docs document, using a new QA tab so existing test content was preserved. Verified parent document/script mapping, pushed to the matching Docs/.clasp.json target, and pulled back Code.js and SidebarJS.html byte-for-byte. Common v8 is pinned with development mode off.

Case Custom option off Custom option on
$$x^2$$ Raw x^2 alt description Same raw fallback
$$a^2+b^2=c^2$$_{Pythagorean theorem} Suffix remains visible; raw LaTeX alt text Suffix becomes Pythagorean theorem alt description
$$z^2$$_{square of {z}} Suffix remains visible Balanced braces preserved in square of {z} description
$$q^2$$_{} Empty suffix remains visible Empty suffix remains visible; raw fallback
$$r^2$$ _{leave visible} Separated suffix remains visible Separated suffix remains visible; raw fallback
$$s^2$$_{unfinished Unclosed suffix remains visible Unclosed suffix remains visible; raw fallback

MathJax: six equations rendered with the option off and on. Native Docs Alt Text UI verified fallback/custom metadata, including each enabled-case description. Single de-render restored the authored custom suffix; De-render All restored the remaining five. Copied source matches the original six fixtures exactly, without duplicate suffixes.

CodeCogs: six equations rendered; native Alt Text UI verified raw fallback and explicit custom text, and the image links confirm CodeCogs URLs. De-render All restored six, with exact source verified again.

Custom option disabled docs-alt-off-before docs-alt-off-rendered docs-alt-off-fallback docs-alt-off-custom-ignored docs-alt-off-derendered
Custom option enabled: all six cases docs-alt-on-rendered docs-alt-on-fallback docs-alt-on-custom docs-alt-on-balanced docs-alt-on-empty docs-alt-on-nonadjacent docs-alt-on-unclosed
Single and all de-render round-trips docs-alt-custom-single-before docs-alt-custom-single-after docs-alt-on-all-after
CodeCogs server renderer docs-alt-codecogs-rendered docs-alt-codecogs-fallback docs-alt-codecogs-custom docs-alt-codecogs-all-after

Release boundary: this PR remains open and its Docs code was pushed to project head for the explicitly requested test. Docs Marketplace remains v95. The separately approved Slides fix was published as v15 in #70. The earlier new sandbox failed at Google OAuth with “This app is blocked”; the existing main Docs add-on ran successfully here.

Divide-By-0 and others added 4 commits September 15, 2026 16:29
The screenshots in this PR's 2026-09-15 comment were taken against the earlier
opt-in revision and show an alt-text checkbox that no longer exists. Recaptured
against this branch pushed to the Docs project head (Common v8, development mode
off, pulled back and verified byte-identical), in a new document tab so the
earlier QA content was left untouched.

Covers the whole _{description} rule in one pass: Advanced Settings with no
checkbox, six equations rendered, Google's own Alt text panel showing the raw
LaTeX fallback, an authored description and a description with nested braces,
and De-render All restoring all six lines character for character.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@Divide-By-0

Copy link
Copy Markdown
Owner Author

New live Docs screenshots — alt text, always on

The screenshots in the 2026-09-15 comment above show an alt-text checkbox that no longer exists; they were taken against the earlier opt-in revision. These replace them.

Captured today in Google Docs against this branch pushed to the Docs Apps Script project head (Common pinned to v8, developmentMode: false), then pulled back and verified byte-identical to what was pushed. Docs Marketplace stays v95 — nothing here is published. The branch was first merged with master so head also carries the merged Inline-fragmentation fix (#71) rather than reverting it. Work happened in a new document tab, so the earlier QA content and the rest of the document were left untouched.

Fixtures

1 raw fallback: $$x^2$$
2 custom description: $$a^2+b^2=c^2$$_{Pythagorean theorem}
3 balanced braces: $$z^2$$_{square of {z}}
4 empty suffix stays visible: $$q^2$$_{}
5 non-adjacent suffix stays visible: $$r^2$$ _{leave visible}
6 unclosed suffix stays visible: $$s^2$$_{unfinished

Source fixtures in a fresh QA tab

There is no setting any more

Advanced Settings now holds only Delimiter Style and Preferred Renderer. Alt text is not something a user has to find and turn on.

Advanced Settings with no alt-text checkbox

Rendered

Status: 6 equations rendered. Cases 2 and 3 consumed their _{...} suffix; cases 4, 5 and 6 left theirs visible, exactly as authored.

Six equations rendered

What a screen reader actually gets

Read out of Google's own Image options → Alt text panel, not from our code.

Case Alt text shown by Docs
$$x^2$$ x^2 — raw LaTeX fallback
$$a^2+b^2=c^2$$_{Pythagorean theorem} Pythagorean theorem
$$z^2$$_{square of {z}} square of {z} — nested braces survive

Alt text showing the raw LaTeX fallback x^2

Alt text showing the authored description Pythagorean theorem

Alt text showing square of {z} with nested braces preserved

Round trip

Status: 6 equations de-rendered, and all six lines come back character for character — including the two suffixes that were consumed at render time and the three that were deliberately left alone. Nothing duplicated, nothing lost.

De-render All restores every fixture exactly


npm test on the merged branch: 159 passing. Write-up and the images live in tests/evidence/pr69.

Not covered by these shots: the CodeCogs server-renderer path (the 2026-09-15 comment covers it and nothing in this revision changed it), and case 4's empty-suffix fallback, which the test suite asserts but I did not photograph.

🤖 Generated with Claude Code

@Divide-By-0
Divide-By-0 merged commit d011ba2 into master Sep 19, 2026
3 checks passed
@Divide-By-0
Divide-By-0 deleted the codex/docs-accessible-alt-text branch September 19, 2026 02:36
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.

1 participant