Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(Markdown): decode character references and escapes in image alt text (#6993)

Cindy Zhangc8d8a1d26147
diff --git a/.changeset/markdown-image-alt-references.md b/.changeset/markdown-image-alt-references.md
new file mode 100644
index 0000000000..a960bd1159
--- /dev/null
+++ b/.changeset/markdown-image-alt-references.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Markdown image alt text shows character references and escapes as the characters they name
+
+`![Fish & chips](…)` gave the image the alt text `Fish & chips`, so a screen reader announced "amp". Alt text now resolves character references and backslash escapes the same way body text does, for inline, standalone, and reference-style images; an escaped `&` and unknown names stay literal.
+
+@cixzhang
diff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsx
index f2a61391da..d6705df48b 100644
--- a/packages/core/src/Markdown/Markdown.test.tsx
+++ b/packages/core/src/Markdown/Markdown.test.tsx
@@ -348,6 +348,17 @@ describe('Markdown', () => {
expect(container.querySelector('code')?.textContent).toBe('&');
});
+ it('names an image with decoded alt text', () => {
+ render(
+ <Markdown>
+ {'![Fish &amp; chips \\*fresh\\*](https://example.com/fish.png)'}
+ </Markdown>,
+ );
+ expect(
+ screen.getByRole('img', {name: 'Fish & chips *fresh*'}),
+ ).toBeInTheDocument();
+ });
+
it('adds target="_blank" to external links', () => {
render(<Markdown>{'[ext](https://example.com)'}</Markdown>);
const link = screen.getByText('ext');
diff --git a/packages/core/src/Markdown/characterReferences.ts b/packages/core/src/Markdown/characterReferences.ts
index 2e486c1d8a..030e27659b 100644
--- a/packages/core/src/Markdown/characterReferences.ts
+++ b/packages/core/src/Markdown/characterReferences.ts
@@ -4,7 +4,9 @@
* @file characterReferences.ts
* @input The HTML named character references, inlined below.
* @output matchCharacterReference: the character a `&name;`, `&#N;`, or
- * `&#xH;` reference names, and where the reference ends.
+ * `&#xH;` reference names, and where the reference ends. decodeLiteralText:
+ * text with backslash escapes and character references resolved, for text
+ * that is not parsed as Markdown, such as an image's alt text.
* @position Used by parser.ts while it parses inline text, so references
* render as the characters they name (spec:AST-061 FR7, DEC-3). Code spans
* and code blocks never reach it and keep references literal.
@@ -73,3 +75,35 @@ export function matchCharacterReference(
(codePoint < 0xd800 || codePoint > 0xdfff);
return {value: isValid ? String.fromCodePoint(codePoint) : '\uFFFD', end};
}
+
+/**
+ * Resolves backslash escapes and character references the way inline parsing
+ * does, for text that is shown as written rather than parsed as Markdown, such
+ * as an image's alt text. An escaped `&` stays literal.
+ */
+export function decodeLiteralText(text: string): string {
+ if (!text.includes('\\') && !text.includes('&')) {
+ return text;
+ }
+ let output = '';
+ let index = 0;
+ while (index < text.length) {
+ const character = text[index];
+ if (character === '\\' && index + 1 < text.length) {
+ output += text[index + 1];
+ index += 2;
+ continue;
+ }
+ if (character === '&') {
+ const reference = matchCharacterReference(text, index);
+ if (reference != null) {
+ output += reference.value;
+ index = reference.end;
+ continue;
+ }
+ }
+ output += character;
+ index++;
+ }
+ return output;
+}
diff --git a/packages/core/src/Markdown/parser.test.ts b/packages/core/src/Markdown/parser.test.ts
index edf95eac19..74caf33297 100644
--- a/packages/core/src/Markdown/parser.test.ts
+++ b/packages/core/src/Markdown/parser.test.ts
@@ -358,6 +358,28 @@ describe('parseInline', () => {
});
});
+ it('decodes character references and escapes in image alt text', () => {
+ expect(parseInline('![Fish &amp; chips \\*fresh\\*](fish.png)')).toEqual([
+ {type: 'image', src: 'fish.png', alt: 'Fish & chips *fresh*'},
+ ]);
+ expect(parseMarkdown('![&copy; 2026 &#169;](logo.png)')[0]).toMatchObject({
+ type: 'image',
+ alt: '\u00a9 2026 \u00a9',
+ });
+ expect(
+ parseMarkdown('![Q&amp;A][logo]\n\n[logo]: /logo.png')[0],
+ ).toMatchObject({
+ type: 'paragraph',
+ children: [{type: 'image', src: '/logo.png', alt: 'Q&A'}],
+ });
+ });
+
+ it('keeps an escaped ampersand and unknown names literal in alt text', () => {
+ expect(parseInline('![\\&amp; &nope;](x.png)')).toEqual([
+ {type: 'image', src: 'x.png', alt: '&amp; &nope;'},
+ ]);
+ });
+
it('handles parentheses in image URLs', () => {
const result = parseInline('![alt](https://example.com/img_(1).png)');
expect(result[0].type).toBe('image');
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
index da3a93d810..dca8858653 100644
--- a/packages/core/src/Markdown/parser.ts
+++ b/packages/core/src/Markdown/parser.ts
@@ -38,7 +38,10 @@ import type {
PreparedMarkdownPlugins,
PreparedSyntaxContribution,
} from './plugins/protocol';
-import {matchCharacterReference} from './characterReferences';
+import {
+ decodeLiteralText,
+ matchCharacterReference,
+} from './characterReferences';
import {isSafeMarkdownParserUrl} from './url';
// ---------------------------------------------------------------------------
@@ -1027,7 +1030,10 @@ function matchReferenceImage(
const label = rawLabel === '' ? alt : rawLabel;
const src = linkDefs.get(normalizeLinkLabel(label));
if (src != null && isSafeMarkdownParserUrl(src)) {
- return {node: {type: 'image', url: src, alt}, end: labelClose + 1};
+ return {
+ node: {type: 'image', url: src, alt: decodeLiteralText(alt)},
+ end: labelClose + 1,
+ };
}
// No match — fall back to a shortcut `![alt]`.
}
@@ -1039,7 +1045,10 @@ function matchReferenceImage(
if (src == null || !isSafeMarkdownParserUrl(src)) {
return null;
}
- return {node: {type: 'image', url: src, alt}, end: altClose + 1};
+ return {
+ node: {type: 'image', url: src, alt: decodeLiteralText(alt)},
+ end: altClose + 1,
+ };
}
// ---------------------------------------------------------------------------
@@ -1535,7 +1544,7 @@ function parseInlineImpl(
nodes.push({
type: 'image',
url: src,
- alt: text.slice(i + 2, altClose),
+ alt: decodeLiteralText(text.slice(i + 2, altClose)),
});
}
i = srcClose + 1;
@@ -2753,7 +2762,11 @@ function parseMarkdownImpl(
line.trim() === imageMatch[0] &&
isSafeMarkdownParserUrl(imageSrc)
) {
- pushBlock({type: 'image', alt: imageMatch[1], url: imageSrc});
+ pushBlock({
+ type: 'image',
+ alt: decodeLiteralText(imageMatch[1]),
+ url: imageSrc,
+ });
index++;
continue;
}