Skip to content

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

TypeScript

fix(markdown): decode escaped pipes in table code spans (#6642)

Cindy Zhang540a520c5c1d
diff --git a/.changeset/markdown-table-escaped-code-pipes.md b/.changeset/markdown-table-escaped-code-pipes.md
new file mode 100644
index 0000000000..88a04d66b6
--- /dev/null
+++ b/.changeset/markdown-table-escaped-code-pipes.md
@@ -0,0 +1,9 @@
+---
+'@astryxdesign/core': patch
+---
+
+[fix] Markdown: render escaped table pipes literally in code spans (#6642)
+
+A `\|` used to keep a pipe inside a table cell now displays as `|` in inline code, matching prose cells without exposing the structural backslash. Completed inline-code spans render only their parsed contents inside `<code>`, without source backticks; standalone inline code otherwise remains unchanged.
+
+@cixzhang
diff --git a/packages/core/src/Markdown/Markdown.spec.md b/packages/core/src/Markdown/Markdown.spec.md
index 15007db10c..61c1e7c6c6 100644
--- a/packages/core/src/Markdown/Markdown.spec.md
+++ b/packages/core/src/Markdown/Markdown.spec.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-09-22
+approved_at: 2026-09-25
owners: [cixzhang]
review_triggers: [api, theming]
verified_by:
@@ -177,6 +177,13 @@ unions. Enabled calls return the explicit `InlineNodeWithMath` and
| FR24 | `createMarkdownFrontmatter()` recognizes only a leading `---` block of unique `key: value` lines, decodes it through the caller's typed parser, stores finite JSON-like metadata on the canonical document, and removes the syntax from rendered content. An unfinished leading block yields no visible Markdown while streaming; malformed or unfinished final input remains ordinary Markdown. Frontmatter has no renderer and requires no Remark compatibility. |
| FR25 | The canonical parser and plugin-construction subpaths remain server-safe and can run function-bearing plugins entirely within server or RSC code. The client-owned `Markdown` component supports traditional and streaming SSR, but plugin entries containing functions cannot be serialized from a Server Component into that client boundary; direct RSC rendering requires a future additive server renderer rather than weakening the plugin protocol. |
+FR23 includes table-level escaping inside inline-code spans: `\|` keeps the pipe
+inside its authored cell, contributes only `|` to the code value and rendered
+text, and produces the same result in full and incremental parsing. A completed
+inline-code span excludes its delimiting backticks from the parsed value and
+renders only that value inside `<code>`; an unmatched backtick remains literal
+text. Outside a table cell, inline code retains its authored backslashes.
+
### Allowed variation
- **AV1 — Parsed content.** The number and ordering of block parts may vary with
@@ -345,7 +352,7 @@ and this change preserves the existing spelling exactly.
| FR17–FR18 | container parse/validation, ownership, and dependency tests | leaf/container declarations, nested containers, foreign read/remove/mint/edit, unmet/misordered dependencies | Plugin-built parsed children, invalid content, lost fallback children, foreign mint/edit, or generic ownership codes. |
| FR19 | diagnostic-channel tests in development and production | every phase, advisory reports, rate suppression, no handler, malformed list, duplicate Core, version skew | A silent production failure, document content in a diagnostic, or one entrypoint throwing where another recovers. |
| FR20–FR22 | canonical/server imports, inference, streaming, preparation, theming tests | server imports, no explicit type args, chunk boundaries, recreated lists, themed/unthemed extensions | Client references, explicit-type workarounds, oscillation, per-render re-preparation, or unreachable opted-in output. |
-| FR23 | parser, renderer, nesting, and public option tests | task-only, plain-only, and mixed ordered/unordered lists at top level and nested; autolink omitted/enabled | A mixed list splits or loses order/state, a plain item becomes a checkbox, or `autolink: 'gfm'` changes non-autolink syntax. |
+| FR23 | parser, incremental, renderer, nesting, and public option tests | mixed lists; escaped prose/code table cells, nested inline code, full/streaming parity; autolink omitted/enabled | A mixed list splits or loses state, an escaped table pipe changes cells or exposes its backslash, or autolink changes other syntax. |
| FR24 | `plugins/frontmatter.test.tsx`, Storybook, and server rendering | complete, malformed, non-leading, LF/CRLF, unfinished streaming, full plugin stack | Metadata syntax renders after completion, unfinished syntax leaks while streaming, typing is lost, or later plugins stop composing. |
| FR25 | `parser.public.test.ts`, plugin SSR tests, and package export checks | server/RSC parsing with plugins, synchronous SSR, suspending renderer streaming boundary | A server import gains `use client`, plugin execution needs serialization, SSR loses fallback, or direct RSC rendering is misrepresented as supported. |
| Public syntax/types | `Markdown.public.test.ts`, core typecheck, and `Markdown.doc.mjs` | Legacy exhaustive switches, math opt-ins, inferred extension-node unions | A released union widens, an enabled union loses nodes, or docs drift from declarations. |
@@ -415,7 +422,7 @@ This projects `spec:AST-036/DEC-5` through `DEC-11` into the component owner in
**Reference:** `component:Markdown/DEC-4`
**Decider:** `cixzhang`, `2026-09-19`
-Markdown's released grammar is an explicit Astryx-owned subset. Task-list markers are item semantics inside the ordinary ordered or unordered list structure, so mixed task and plain items stay in one compatible list and each item retains its own state at every nesting level. Released table and task-list syntax remains enabled by default. The optional `autolink: 'gfm'` value adds only the documented autolink behavior; it neither enables another syntax feature nor changes list structure.
+Markdown's released grammar is an explicit Astryx-owned subset. Task-list markers are item semantics inside the ordinary ordered or unordered list structure, so mixed task and plain items stay in one compatible list and each item retains its own state at every nesting level. Released table and task-list syntax remains enabled by default. A backslash-escaped pipe inside a table cell is structural source syntax: it keeps the pipe in that cell and contributes only the literal pipe to rendered prose or inline code, with the same result in full and incremental parsing. The optional `autolink: 'gfm'` value adds only the documented autolink behavior; it neither enables another syntax feature nor changes list structure.
This keeps documents stable as Astryx adds or declines individual ecosystem features. It rejects a blanket CommonMark or GFM conformance claim, aggregate all-task/all-plain classification, an implicit whole-grammar mode switch, and silently enabling future GFM features under the existing autolink option.
diff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsx
index e1cc5f8eea..2b878261e4 100644
--- a/packages/core/src/Markdown/Markdown.test.tsx
+++ b/packages/core/src/Markdown/Markdown.test.tsx
@@ -297,9 +297,13 @@ describe('Markdown', () => {
expect(screen.getByText('struck').tagName).toBe('DEL');
});
- it('renders inline code with Code', () => {
- render(<Markdown>{'Use `code` here'}</Markdown>);
- expect(screen.getByText('code').tagName).toBe('CODE');
+ it('renders inline code as delimiter-free <code> content', () => {
+ const {container} = render(<Markdown>{'Use `code` here'}</Markdown>);
+ const code = container.querySelector('code');
+ expect(code).toBeInTheDocument();
+ expect(code).toHaveTextContent('code');
+ expect(code?.textContent).toBe('code');
+ expect(container.textContent).toBe('Use code here');
});
it('renders code blocks with CodeBlock', () => {
@@ -440,6 +444,23 @@ describe('Markdown', () => {
expect(document.querySelectorAll('td')).toHaveLength(2);
});
+ it('renders escaped table pipes without exposing the escape in code spans', () => {
+ render(
+ <Markdown>
+ {
+ '| Concept | TypeScript |\n| --- | --- |\n| Null safety | `T \\| null` |'
+ }
+ </Markdown>,
+ );
+
+ const cells = document.querySelectorAll('tbody td');
+ expect(Array.from(cells).map(cell => cell.textContent)).toEqual([
+ 'Null safety',
+ 'T | null',
+ ]);
+ expect(cells[1].querySelector('code')).toHaveTextContent('T | null');
+ });
+
it('makes the table scroll wrapper keyboard-focusable', () => {
render(<Markdown>{'| A | B |\n| --- | --- |\n| 1 | 2 |'}</Markdown>);
const table = document.querySelector('table');
diff --git a/packages/core/src/Markdown/incremental.test.ts b/packages/core/src/Markdown/incremental.test.ts
index 77e2eb1bef..be18a46145 100644
--- a/packages/core/src/Markdown/incremental.test.ts
+++ b/packages/core/src/Markdown/incremental.test.ts
@@ -740,6 +740,37 @@ describe('streaming structural suppression', () => {
);
});
+ it.each([false, true])(
+ 'decodes escaped pipes in code spans during production streaming (sourceRanges=%s)',
+ sourceRanges => {
+ const text =
+ 'Intro\n\n| Concept | TypeScript |\n| --- | --- |\n| Null safety | **`T \\| null`** |';
+ const options = {sourceRanges, math: false as const};
+ const full = parseMarkdown(text, options);
+
+ for (const trimsArtifacts of [false, true]) {
+ const state = createIncrementalState();
+ let streamed = parseMarkdownIncremental('', state, options);
+ for (let end = 1; end <= text.length; end++) {
+ const prefix = text.slice(0, end);
+ streamed = parseMarkdownIncremental(
+ trimsArtifacts ? trimStreamingArtifacts(prefix, options) : prefix,
+ state,
+ options,
+ );
+ }
+
+ expect(state.settledText).toBe('Intro');
+ expect(streamed).toEqual(full);
+ expect(streamed).toHaveLength(2);
+ expect(streamed[1].type).toBe('table');
+ expect(visibleText(streamed[1])).toBe(
+ 'Concept TypeScript\nNull safety T | null',
+ );
+ }
+ },
+ );
+
it('still holds back a lone header whose pipes are unescaped', () => {
const state = createIncrementalState();
diff --git a/packages/core/src/Markdown/parser.test.ts b/packages/core/src/Markdown/parser.test.ts
index bf390a15b0..20be607b8e 100644
--- a/packages/core/src/Markdown/parser.test.ts
+++ b/packages/core/src/Markdown/parser.test.ts
@@ -42,6 +42,11 @@ describe('parseInline', () => {
expect(result).toEqual([{type: 'code', content: 'const x'}]);
});
+ it('keeps backslash escapes literal inside standalone inline code', () => {
+ const result = parseInline('`T \\| null`');
+ expect(result).toEqual([{type: 'code', content: 'T \\| null'}]);
+ });
+
it('leaves math delimiters as literal text by default', () => {
expect(parseInline('Euler: $e^{i * pi} + 1 = 0$.')).toEqual([
{type: 'text', content: 'Euler: $e^{i * pi} + 1 = 0$.'},
@@ -681,17 +686,24 @@ describe('parseMarkdown', () => {
// --- Table with escaped pipes ---
- it('handles escaped pipes in table cells', () => {
+ it('decodes escaped pipes in table code spans without changing prose nodes', () => {
const input =
- '| Concept | TypeScript |\n| --- | --- |\n| Null safety | `T \\| null` |\n| Union | `A \\| B \\| C` |';
+ '| Concept | TypeScript |\n| --- | --- |\n| Prose | A \\| B |\n| Null safety | `T \\| null` |\n| Union | `A \\| B \\| C` |';
const result = parseMarkdown(input);
expect(result[0].type).toBe('table');
if (result[0].type === 'table') {
expect(result[0].headers).toHaveLength(2);
- expect(result[0].rows).toHaveLength(2);
- // The cell should contain the escaped pipe as inline content
- expect(result[0].rows[0]).toHaveLength(2);
- expect(result[0].rows[1]).toHaveLength(2);
+ expect(result[0].rows).toHaveLength(3);
+ expect(result[0].rows[0][1].children).toEqual([
+ {type: 'text', content: 'A '},
+ {type: 'text', content: '| B'},
+ ]);
+ expect(result[0].rows[1][1].children).toEqual([
+ {type: 'code', content: 'T | null'},
+ ]);
+ expect(result[0].rows[2][1].children).toEqual([
+ {type: 'code', content: 'A | B | C'},
+ ]);
}
});
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
index 418c30bdd6..c22e4985b7 100644
--- a/packages/core/src/Markdown/parser.ts
+++ b/packages/core/src/Markdown/parser.ts
@@ -945,6 +945,7 @@ function matchReferenceLink(
start: number,
linkDefs: ReadonlyMap<string, string>,
opts: ResolvedOptions,
+ context: 'default' | 'tableCell',
): {
node: MarkdownAstPhrasingContent<RuntimeExtensionNode>;
end: number;
@@ -969,7 +970,11 @@ function matchReferenceLink(
node: {
type: 'link',
url: href,
- children: parseInlineImpl(linkText, protectedInlineOptions(opts)),
+ children: parseInlineImpl(
+ linkText,
+ protectedInlineOptions(opts),
+ context,
+ ),
},
end: labelClose + 1,
};
@@ -990,7 +995,11 @@ function matchReferenceLink(
node: {
type: 'link',
url: href,
- children: parseInlineImpl(linkText, protectedInlineOptions(opts)),
+ children: parseInlineImpl(
+ linkText,
+ protectedInlineOptions(opts),
+ context,
+ ),
},
end: textClose + 1,
};
@@ -1425,14 +1434,16 @@ function parseInlineAstRuntime(
function parseInlineEntry(
text: string,
opts: ResolvedOptions,
+ context: 'default' | 'tableCell' = 'default',
): MarkdownAstPhrasingContent<RuntimeExtensionNode>[] {
- const nodes = parseInlineImpl(text, opts);
+ const nodes = parseInlineImpl(text, opts, context);
return opts.autolink === 'gfm' ? transformAutolinks(nodes) : nodes;
}
function parseInlineImpl(
text: string,
opts: ResolvedOptions,
+ context: 'default' | 'tableCell' = 'default',
): MarkdownAstPhrasingContent<RuntimeExtensionNode>[] {
const nodes: MarkdownAstPhrasingContent<RuntimeExtensionNode>[] = [];
// Only a plugin that actually contributes INLINE syntax may cost anything
@@ -1461,7 +1472,10 @@ function parseInlineImpl(
if (closeIndex !== -1) {
nodes.push({
type: 'inlineCode',
- value: text.slice(openIndex, closeIndex),
+ value:
+ context === 'tableCell'
+ ? text.slice(openIndex, closeIndex).replace(/\\\|/g, '|')
+ : text.slice(openIndex, closeIndex),
});
i = closeIndex + tickCount;
continue;
@@ -1551,6 +1565,7 @@ function parseInlineImpl(
children: parseInlineImpl(
text.slice(i + 1, textClose),
protectedInlineOptions(opts),
+ context,
),
});
}
@@ -1562,7 +1577,7 @@ function parseInlineImpl(
// --- Reference link [text][label] / [text][] / [text] ---
if (opts.linkDefs != null && text[i] === '[') {
- const ref = matchReferenceLink(text, i, opts.linkDefs, opts);
+ const ref = matchReferenceLink(text, i, opts.linkDefs, opts, context);
if (ref) {
nodes.push(ref.node);
i = ref.end;
@@ -1590,7 +1605,11 @@ function parseInlineImpl(
children: [
{
type: 'emphasis',
- children: parseInlineImpl(text.slice(i + 3, closeIndex), opts),
+ children: parseInlineImpl(
+ text.slice(i + 3, closeIndex),
+ opts,
+ context,
+ ),
},
],
});
@@ -1617,7 +1636,11 @@ function parseInlineImpl(
) {
nodes.push({
type: 'strong',
- children: parseInlineImpl(text.slice(i + 2, closeIndex), opts),
+ children: parseInlineImpl(
+ text.slice(i + 2, closeIndex),
+ opts,
+ context,
+ ),
});
i = closeIndex + 2;
continue;
@@ -1631,7 +1654,11 @@ function parseInlineImpl(
if (closeIndex !== -1) {
nodes.push({
type: 'delete',
- children: parseInlineImpl(text.slice(i + 2, closeIndex), opts),
+ children: parseInlineImpl(
+ text.slice(i + 2, closeIndex),
+ opts,
+ context,
+ ),
});
i = closeIndex + 2;
continue;
@@ -1652,7 +1679,11 @@ function parseInlineImpl(
) {
nodes.push({
type: 'emphasis',
- children: parseInlineImpl(text.slice(i + 1, closeIndex), opts),
+ children: parseInlineImpl(
+ text.slice(i + 1, closeIndex),
+ opts,
+ context,
+ ),
});
i = closeIndex + 1;
continue;
@@ -2182,7 +2213,10 @@ function parseTable(
): {node: MarkdownAstBlockContent<RuntimeExtensionNode>; nextIndex: number} {
const headers: MarkdownAstTableCell<RuntimeExtensionNode>[] = splitTableRow(
lines[lineIndex],
- ).map(cell => ({type: 'tableCell', children: parseInlineEntry(cell, opts)}));
+ ).map(cell => ({
+ type: 'tableCell',
+ children: parseInlineEntry(cell, opts, 'tableCell'),
+ }));
const alignments: TableAlignment[] = splitTableRow(lines[lineIndex + 1]).map(
cell => {
const trimmed = cell.trim();
@@ -2208,7 +2242,7 @@ function parseTable(
type: 'tableRow',
children: splitTableRow(lines[rowIndex]).map(cell => ({
type: 'tableCell',
- children: parseInlineEntry(cell, opts),
+ children: parseInlineEntry(cell, opts, 'tableCell'),
})),
});
rowIndex++;