Skip to content

Let people edit a picture's alt text from the media toolbar #798

Open

Description

@HMarzban

A picture in a pad can carry alt text, but nobody can edit it. Alt text is the description a screen reader reads out in place of the picture. The image node stores it in its alt attribute (extensions/extension-hypermultimedia/src/nodes/image/image.ts:96), and Markdown import fills it from ![alt](src). After that, no surface can change it.

What we found

On 2026-11-15 we needed to change one word in the alt text of the 2.3.0 banner on the live demo pad (docs.plus/demo). None of the three ways worked:

  • Media toolbar. The inline actions are Align, Caption, View original, Download and Comment. The More actions menu holds Replace URL, Copy and Delete (BASE_ACTIONS in extensions/extension-hypermultimedia/src/toolbar/actions.ts:141). None of them edits alt text.
  • MCP tools. read_document shows a picture only as [image], and a connected app never edits media, by design (apps/hocuspocus.server/CLAUDE.md). So an AI app cannot fix alt text either.
  • Replace the pad from a Markdown file. That would change the alt text, but it gives every heading a new id, so heading chats lose their rooms (Settings file replace re-keys every heading, so the digest rewrites whole sections and heading chats lose their rooms #474). We did not use it.

So a wrong or missing description stays on the picture for good, unless someone deletes the picture and inserts it again.

Who it affects

  • Screen reader users. They hear the stored alt text, or nothing when it is empty.
  • Pad owners who import Markdown. A typo in ![alt] cannot be fixed after import.
  • Owners of public pads like the demo, where the alt text is part of what a reader gets.

What other editors do

Google Docs and Microsoft Word both let you edit a picture's alt text from the picture's own menu. This is read from memory and was not checked against their help pages today. We have not checked Notion. Per AGENTS.md §Workflow And Review Expectations, the builder should confirm the majority behaviour first.

Proposed change

Add an Alt text action to the media toolbar for pictures. It opens a small form with one text field and Save, like the Replace URL form (extensions/extension-hypermultimedia/src/toolbar/replaceUrl.ts). Save writes the alt attribute in one transaction, so Undo restores the old text. Markdown export already writes ![alt] (extensions/extension-hypermultimedia/src/markdown/typedMediaMarkdown.ts:358), so the new text round-trips with no other change.

Decisions

  1. Where does the action live? Recommended: in the extension's BASE_ACTIONS, because alt is a core attribute of the published image node, and every user of the extension gains it. The other option is a webapp-only action through the mediaActions hook (apps/webapp/src/components/TipTap/TipTap.tsx:255).
  2. Inline or in More actions? Recommended: in More actions, beside Replace URL, so the inline row does not grow.
  3. Which media kinds? Recommended: pictures only, for now. Video and embeds have no alt today.
  4. Who may edit? Recommended: anyone who can edit the pad, like Caption. A read-only pad hides the action.
  5. Should MCP get an alt text tool? Recommended: no, not in this issue. The rule that connected apps never edit media stays. A separate ruling can revisit it.

Done when

  • A picture's More actions menu has Alt text, and Save changes the alt attribute.
  • Undo restores the old text.
  • Markdown export writes the new text.
  • The extension CHANGELOG and the image README (extensions/extension-hypermultimedia/src/nodes/image/README.md) list the new action.
  • The 2.3.0 banner on the demo pad says "…a section dragged in the TOC". That fixes the one leftover from the 2026-11-15 rename of "outline" to "TOC".
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions