Skip to content

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

TypeScript

Markdown: support CommonMark link reference definitions (#3621)

Alexander Blomcbfd87bcf172
diff --git a/.changeset/markdown-link-reference-definitions.md b/.changeset/markdown-link-reference-definitions.md
new file mode 100644
index 0000000000..e77ef5073d
--- /dev/null
+++ b/.changeset/markdown-link-reference-definitions.md
@@ -0,0 +1,6 @@
+---
+'@astryxdesign/core': patch
+---
+
+[feat] Markdown: support CommonMark link reference definitions. Reference-style "footer" links — full `[text][label]`, collapsed `[text][]`, and shortcut `[text]` (plus their `![alt]` image forms) — now resolve against a `[label]: destination "title"` block, which is stripped from the output instead of leaking as a visible paragraph. Labels match case-insensitively with collapsed whitespace; top-level definitions are collected across the document (so a reference can precede its definition, including in the streaming/incremental parser, whose settled-block cache invalidates when definitions change). Footnotes (`[^1]`) are intentionally left untouched. Known limit: a definition nested inside a blockquote/list resolves within that container but is not yet exposed document-wide. (#3621)
+@lexs
diff --git a/packages/core/src/Markdown/Markdown.test.tsx b/packages/core/src/Markdown/Markdown.test.tsx
index 4bb8e33448..242c4a398a 100644
--- a/packages/core/src/Markdown/Markdown.test.tsx
+++ b/packages/core/src/Markdown/Markdown.test.tsx
@@ -95,6 +95,29 @@ describe('Markdown', () => {
expect(link.getAttribute('rel')).toBe('noopener noreferrer');
});
+ it('renders a footer reference-style link as an anchor', () => {
+ // The XDS parser previously had no reference-definition support, so this
+ // rendered as literal `[the docs][docs]` text with the definition leaking
+ // as a paragraph. It now resolves to a real anchor.
+ render(
+ <Markdown>
+ {'See [the docs][docs] here.\n\n[docs]: https://example.com/docs\n'}
+ </Markdown>,
+ );
+ const link = screen.getByText('the docs');
+ expect(link.tagName).toBe('A');
+ expect(link.getAttribute('href')).toBe('https://example.com/docs');
+ // The definition line must not leak into the rendered output.
+ expect(screen.queryByText(/\[docs\]:/)).toBeNull();
+ });
+
+ it('renders a shortcut reference-style link as an anchor', () => {
+ render(<Markdown>{'See [the docs].\n\n[the docs]: /docs'}</Markdown>);
+ const link = screen.getByText('the docs');
+ expect(link.tagName).toBe('A');
+ expect(link.getAttribute('href')).toBe('/docs');
+ });
+
it('does not add target="_blank" to relative links', () => {
render(<Markdown>{'[internal](/page)'}</Markdown>);
const link = screen.getByText('internal');
diff --git a/packages/core/src/Markdown/incremental.test.ts b/packages/core/src/Markdown/incremental.test.ts
index ca88599180..63bbbf6061 100644
--- a/packages/core/src/Markdown/incremental.test.ts
+++ b/packages/core/src/Markdown/incremental.test.ts
@@ -650,3 +650,39 @@ describe('streaming end-to-end: no raw syntax visible', () => {
});
});
});
+
+describe('parseMarkdownIncremental link reference definitions', () => {
+ function firstLinkHref(blocks: BlockNode[]): string | undefined {
+ for (const block of blocks) {
+ if (block.type === 'paragraph') {
+ for (const node of block.children) {
+ if (node.type === 'link') {
+ return node.href;
+ }
+ }
+ }
+ }
+ return undefined;
+ }
+
+ it('resolves a footer reference streamed across chunks (matches full parse)', () => {
+ const text = 'See [the docs][d] here.\n\n[d]: https://example.com/d\n';
+ const {final} = simulateStreaming(text, 5);
+ expect(final).toEqual(parseMarkdown(text));
+ expect(firstLinkHref(final)).toBe('https://example.com/d');
+ });
+
+ it('re-resolves an already-settled reference once its definition arrives', () => {
+ const state = createIncrementalState();
+ // The reference paragraph settles (blank line) before the definition.
+ parseMarkdownIncremental('See [d] here.\n\n', state);
+ const before = parseMarkdownIncremental('See [d] here.\n\n[d', state);
+ expect(firstLinkHref(before)).toBeUndefined();
+ // Definition completes — the settled paragraph must pick up the link.
+ const after = parseMarkdownIncremental(
+ 'See [d] here.\n\n[d]: /docs\n',
+ state,
+ );
+ expect(firstLinkHref(after)).toBe('/docs');
+ });
+});
diff --git a/packages/core/src/Markdown/parser.test.ts b/packages/core/src/Markdown/parser.test.ts
index aaa66d45e6..b217b41515 100644
--- a/packages/core/src/Markdown/parser.test.ts
+++ b/packages/core/src/Markdown/parser.test.ts
@@ -2,6 +2,7 @@
import {describe, it, expect} from 'vitest';
import {parseMarkdown, parseInline} from './parser';
+import type {InlineNode} from './parser';
describe('parseInline', () => {
it('parses plain text', () => {
@@ -946,3 +947,212 @@ describe('citation parsing', () => {
});
});
});
+
+// ---------------------------------------------------------------------------
+// Link reference definitions
+// ---------------------------------------------------------------------------
+
+describe('link reference definitions', () => {
+ // Collect every link/image node across a block tree for concise assertions.
+ function collectLinks(
+ nodes: InlineNode[],
+ ): {type: string; href?: string; src?: string; text: string}[] {
+ const out: {type: string; href?: string; src?: string; text: string}[] = [];
+ const textOf = (inlineNodes: InlineNode[]): string =>
+ inlineNodes
+ .map(inline =>
+ inline.type === 'text'
+ ? inline.content
+ : 'children' in inline
+ ? textOf(inline.children)
+ : '',
+ )
+ .join('');
+ for (const node of nodes) {
+ if (node.type === 'link') {
+ out.push({type: 'link', href: node.href, text: textOf(node.children)});
+ } else if (node.type === 'image') {
+ out.push({type: 'image', src: node.src, text: node.alt});
+ } else if ('children' in node) {
+ out.push(...collectLinks(node.children));
+ }
+ }
+ return out;
+ }
+
+ function paragraphLinks(input: string) {
+ const blocks = parseMarkdown(input);
+ const links = blocks.flatMap(block =>
+ block.type === 'paragraph' ? collectLinks(block.children) : [],
+ );
+ return {blocks, links};
+ }
+
+ it('resolves a full reference `[text][label]` and drops the definition', () => {
+ const {blocks, links} = paragraphLinks(
+ 'See [the docs][docs] here.\n\n[docs]: https://example.com/docs\n',
+ );
+ // Only the paragraph survives; the definition line produces no block.
+ expect(blocks).toHaveLength(1);
+ expect(blocks[0].type).toBe('paragraph');
+ expect(links).toEqual([
+ {type: 'link', href: 'https://example.com/docs', text: 'the docs'},
+ ]);
+ });
+
+ it('resolves a collapsed reference `[text][]`', () => {
+ const {links} = paragraphLinks(
+ 'See [the docs][].\n\n[the docs]: https://example.com/docs',
+ );
+ expect(links).toEqual([
+ {type: 'link', href: 'https://example.com/docs', text: 'the docs'},
+ ]);
+ });
+
+ it('resolves a shortcut reference `[text]`', () => {
+ const {links} = paragraphLinks(
+ 'See [the docs].\n\n[the docs]: https://example.com/docs',
+ );
+ expect(links).toEqual([
+ {type: 'link', href: 'https://example.com/docs', text: 'the docs'},
+ ]);
+ });
+
+ it('resolves a reference that appears before its definition', () => {
+ const {links} = paragraphLinks('[foo]\n\n[foo]: /bar');
+ expect(links).toEqual([{type: 'link', href: '/bar', text: 'foo'}]);
+ });
+
+ it('matches labels case-insensitively with collapsed whitespace', () => {
+ const {links} = paragraphLinks(
+ 'See [The Docs][DOCS].\n\n[docs]: https://example.com/d',
+ );
+ expect(links).toEqual([
+ {type: 'link', href: 'https://example.com/d', text: 'The Docs'},
+ ]);
+ });
+
+ it('supports an angle-bracket destination and a title', () => {
+ const {links} = paragraphLinks(
+ 'See [x].\n\n[x]: <https://example.com/x> "the title"',
+ );
+ expect(links).toEqual([
+ {type: 'link', href: 'https://example.com/x', text: 'x'},
+ ]);
+ });
+
+ it('absorbs a title on the line after a title-less definition', () => {
+ const {blocks, links} = paragraphLinks(
+ 'See [x].\n\n[x]: https://example.com/x\n "the title"\n',
+ );
+ // The continuation title line must not leak as its own paragraph.
+ expect(blocks).toHaveLength(1);
+ expect(links).toEqual([
+ {type: 'link', href: 'https://example.com/x', text: 'x'},
+ ]);
+ });
+
+ it('resolves an empty angle-bracket destination to an empty href', () => {
+ const {blocks, links} = paragraphLinks('[foo]\n\n[foo]: <>');
+ expect(blocks).toHaveLength(1);
+ expect(links).toEqual([{type: 'link', href: '', text: 'foo'}]);
+ });
+
+ it('recognizes a definition immediately after a heading (no blank line)', () => {
+ const {blocks, links} = paragraphLinks('# Title\n[x]: /url\n\n[x]');
+ expect(blocks.map(block => block.type)).toEqual(['heading', 'paragraph']);
+ expect(links).toEqual([{type: 'link', href: '/url', text: 'x'}]);
+ });
+
+ it('recognizes a definition immediately after a closed code fence', () => {
+ const {blocks, links} = paragraphLinks('```\ncode\n```\n[x]: /url\n\n[x]');
+ expect(blocks.map(block => block.type)).toEqual(['codeblock', 'paragraph']);
+ expect(links).toEqual([{type: 'link', href: '/url', text: 'x'}]);
+ });
+
+ it('uses the first definition when a label is defined twice', () => {
+ const {links} = paragraphLinks('[a]\n\n[a]: /first\n[a]: /second');
+ expect(links).toEqual([{type: 'link', href: '/first', text: 'a'}]);
+ });
+
+ it('resolves a blockquote-nested definition even with a top-level definition present', () => {
+ const blocks = parseMarkdown('[outer]: /o\n\n> [inner]\n>\n> [inner]: /i');
+ const quote = blocks.find(block => block.type === 'blockquote');
+ expect(quote?.type).toBe('blockquote');
+ if (quote != null && quote.type === 'blockquote') {
+ const links = quote.children.flatMap(block =>
+ block.type === 'paragraph' ? collectLinks(block.children) : [],
+ );
+ expect(links).toEqual([{type: 'link', href: '/i', text: 'inner'}]);
+ }
+ });
+
+ it('resolves a reference image `![alt][label]`', () => {
+ const {links} = paragraphLinks('![logo][l]\n\n[l]: /logo.png');
+ expect(links).toEqual([{type: 'image', src: '/logo.png', text: 'logo'}]);
+ });
+
+ it('does not treat a whitespace-only second label as collapsed', () => {
+ // `[foo][ ]` is a full reference to the empty (normalized) label and matches
+ // nothing; `[foo]` still resolves as a shortcut and `[ ]` stays literal.
+ const blocks = parseMarkdown('[foo][ ]\n\n[foo]: /f');
+ expect(blocks[0].type).toBe('paragraph');
+ if (blocks[0].type === 'paragraph') {
+ expect(collectLinks(blocks[0].children)).toEqual([
+ {type: 'link', href: '/f', text: 'foo'},
+ ]);
+ const literal = blocks[0].children
+ .map(node => (node.type === 'text' ? node.content : ''))
+ .join('');
+ expect(literal).toContain('[ ]');
+ }
+ });
+
+ it('leaves an unresolved reference as literal text', () => {
+ const {blocks, links} = paragraphLinks('See [the docs][missing].');
+ expect(links).toEqual([]);
+ expect(blocks[0].type).toBe('paragraph');
+ if (blocks[0].type === 'paragraph') {
+ expect(blocks[0].children).toContainEqual({
+ type: 'text',
+ content: 'See [the docs][missing].',
+ });
+ }
+ });
+
+ it('does not resolve a definition or reference inside a code fence', () => {
+ const blocks = parseMarkdown('```\n[x]\n[x]: /should-not-resolve\n```');
+ expect(blocks).toHaveLength(1);
+ expect(blocks[0].type).toBe('codeblock');
+ if (blocks[0].type === 'codeblock') {
+ expect(blocks[0].content).toBe('[x]\n[x]: /should-not-resolve');
+ }
+ });
+
+ it('does not treat a definition-shaped line as a definition mid-paragraph', () => {
+ // CommonMark: a definition cannot interrupt a paragraph.
+ const {blocks, links} = paragraphLinks('Foo\n[bar]: /baz');
+ expect(links).toEqual([]);
+ expect(blocks).toHaveLength(1);
+ expect(blocks[0].type).toBe('paragraph');
+ });
+
+ it('leaves footnote markers and definitions untouched', () => {
+ const blocks = parseMarkdown(
+ 'A claim.[^1]\n\n[^1]: https://example.com/note',
+ );
+ // No link nodes; the `[^1]` marker stays literal and `[^1]:` is not
+ // treated as a link reference definition (footnotes are out of scope).
+ const links = blocks.flatMap(block =>
+ block.type === 'paragraph' ? collectLinks(block.children) : [],
+ );
+ expect(links).toEqual([]);
+ expect(blocks).toHaveLength(2);
+ });
+
+ it('leaves ordinary bracketed text with no definition alone', () => {
+ const {links, blocks} = paragraphLinks('an array like [1, 2, 3] here');
+ expect(links).toEqual([]);
+ expect(blocks[0].type).toBe('paragraph');
+ });
+});
diff --git a/packages/core/src/Markdown/parser.ts b/packages/core/src/Markdown/parser.ts
index 0e52ab913c..5583caa9f6 100644
--- a/packages/core/src/Markdown/parser.ts
+++ b/packages/core/src/Markdown/parser.ts
@@ -81,6 +81,13 @@ export type ParseOptions = {
type ResolvedOptions = {
readonly sourceIds: ReadonlySet<string> | undefined;
readonly autolink: 'gfm' | undefined;
+ /**
+ * Link reference definitions (`[label]: url`) collected from the whole
+ * document, keyed by normalized label. Internal only — populated by the
+ * block parser, never by the public `ParseOptions`. Enables `parseInlineImpl`
+ * to resolve full/collapsed/shortcut reference links and images.
+ */
+ readonly linkDefs?: ReadonlyMap<string, string>;
};
const EMPTY_OPTS: ResolvedOptions = {sourceIds: undefined, autolink: undefined};
@@ -103,6 +110,228 @@ function resolveOptions(
return {sourceIds: opts.sourceIds, autolink: opts.autolink};
}
+// ---------------------------------------------------------------------------
+// Link reference definitions
+// ---------------------------------------------------------------------------
+
+// A CommonMark link reference definition line: up to 3 leading spaces, a
+// bracketed label, `:`, a destination (bare or `<...>`), and an optional
+// same-line title (captured as group 4 so a title-less definition can absorb a
+// title on the following line). `^`-leading labels (`[^1]:`) are footnote
+// definitions — a separate, unsupported feature — and are excluded so they
+// pass through verbatim.
+const LINK_DEFINITION_RE =
+ /^ {0,3}\[([^\]^](?:\\.|[^\]\\])*)\]:[ \t]*(?:<([^<>\n]*)>|(\S+))([ \t]+(?:"[^"\n]*"|'[^'\n]*'|\([^()\n]*\)))?[ \t]*$/;
+
+// A line that is nothing but a title — the continuation form allowed when a
+// definition's destination is followed by its title on the next line.
+const LINK_TITLE_ONLY_RE = /^ {0,3}(?:"[^"\n]*"|'[^'\n]*'|\([^()\n]*\))[ \t]*$/;
+
+// CommonMark matches reference labels case-insensitively with leading/trailing
+// whitespace stripped and internal whitespace runs collapsed to one space.
+function normalizeLinkLabel(label: string): string {
+ return label.trim().replace(/\s+/g, ' ').toLowerCase();
+}
+
+function matchLinkDefinition(
+ line: string,
+): {label: string; destination: string; hasTitle: boolean} | null {
+ const match = LINK_DEFINITION_RE.exec(line);
+ if (match == null) {
+ return null;
+ }
+ const label = normalizeLinkLabel(match[1]);
+ // `match[2]` is the `<...>` destination (present but possibly empty, e.g.
+ // `<>` → empty href, valid per CommonMark); `match[3]` is the bare
+ // destination (always non-empty). One of the two always matches.
+ const destination = match[2] != null ? match[2] : match[3];
+ if (label === '' || destination == null) {
+ return null;
+ }
+ return {label, destination, hasTitle: match[4] != null};
+}
+
+/**
+ * Collect link reference definitions from the whole document and return the
+ * input with the definition lines removed. A definition is recognized at a
+ * block boundary — document start, after a blank line, after another
+ * definition, or after a self-contained block (heading / thematic break /
+ * closed fenced code) — but never inside a fenced code block or as a lazy
+ * continuation of a paragraph, honoring CommonMark's rule that a definition
+ * cannot interrupt a paragraph. First definition wins, and definitions produce
+ * no output so stripping unreferenced ones is correct.
+ *
+ * Scope limit: definitions are collected at the top level only, and a
+ * definition directly following a list, blockquote, or table (with no blank
+ * line between) is not recognized. A definition nested inside a blockquote or
+ * list item resolves within that container (via the recursive parse) but is
+ * not exposed to references elsewhere in the document, unlike full CommonMark
+ * where every definition is global. Separating a footer definition block with
+ * a blank line — the usual form — always works.
+ */
+function extractLinkDefinitions(input: string): {
+ defs: ReadonlyMap<string, string>;
+ cleaned: string;
+} {
+ const lines = input.split('\n');
+ const defs = new Map<string, string>();
+ const keep = new Array<boolean>(lines.length).fill(true);
+ let atBoundary = true;
+ let inFence = false;
+ let fenceMarker = '';
+
+ for (let index = 0; index < lines.length; index++) {
+ const line = lines[index];
+ if (inFence) {
+ if (line.startsWith(fenceMarker)) {
+ inFence = false;
+ fenceMarker = '';
+ // The line after a closed fence begins a new block.
+ atBoundary = true;
+ } else {
+ atBoundary = false;
+ }
+ continue;
+ }
+ const fenceMatch = line.match(/^(`{3,}|~{3,})/);
+ if (fenceMatch) {
+ inFence = true;
+ fenceMarker = fenceMatch[1];
+ atBoundary = false;
+ continue;
+ }
+ if (line.trim() === '') {
+ atBoundary = true;
+ continue;
+ }
+ if (atBoundary) {
+ const def = matchLinkDefinition(line);
+ if (def != null) {
+ if (!defs.has(def.label)) {
+ defs.set(def.label, def.destination);
+ }
+ keep[index] = false;
+ // A title-less definition absorbs a title on the following line
+ // (CommonMark), which then also produces no output.
+ if (
+ !def.hasTitle &&
+ index + 1 < lines.length &&
+ LINK_TITLE_ONLY_RE.test(lines[index + 1])
+ ) {
+ keep[index + 1] = false;
+ index++;
+ }
+ // Consecutive definitions stay at a block boundary.
+ continue;
+ }
+ }
+ // A heading or thematic break is a self-contained single-line block, so
+ // the next line begins a new block where a definition may appear.
+ atBoundary = /^ {0,3}#{1,6}(?: |\t|$)/.test(line) || isHorizontalRule(line);
+ }
+
+ if (defs.size === 0) {
+ return {defs, cleaned: input};
+ }
+ const cleaned = lines.filter((_, index) => keep[index]).join('\n');
+ return {defs, cleaned};
+}
+
+/** Order-independent signature of a link-definition set, for cache checks. */
+function linkDefsSignature(defs: ReadonlyMap<string, string>): string {
+ if (defs.size === 0) {
+ return '';
+ }
+ return [...defs]
+ .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0))
+ .map(([label, dest]) => `${label}\u0000${dest}`)
+ .join('\u0001');
+}
+
+/**
+ * Resolve a full (`[text][label]`), collapsed (`[text][]`), or shortcut
+ * (`[text]`) reference at `start` (which points at `[`) against `linkDefs`.
+ * Returns the node plus the index just past the reference, or null when it is
+ * not a resolvable reference (caller falls through to literal handling).
+ */
+function matchReferenceLink(
+ text: string,
+ start: number,
+ linkDefs: ReadonlyMap<string, string>,
+ opts: ResolvedOptions,
+): {node: InlineNode; end: number} | null {
+ const textClose = text.indexOf(']', start + 1);
+ if (textClose === -1) {
+ return null;
+ }
+ const linkText = text.slice(start + 1, textClose);
+ // Full `[text][label]` / collapsed `[text][]` — a matching definition wins.
+ if (text[textClose + 1] === '[') {
+ const labelClose = text.indexOf(']', textClose + 2);
+ if (labelClose !== -1) {
+ const rawLabel = text.slice(textClose + 2, labelClose);
+ // Only truly-empty brackets are the collapsed form; a whitespace-only
+ // label (`[ ]`) is a full reference whose normalized label is empty and
+ // matches nothing.
+ const label = rawLabel === '' ? linkText : rawLabel;
+ const href = linkDefs.get(normalizeLinkLabel(label));
+ if (href != null) {
+ return {
+ node: {type: 'link', href, children: parseInlineImpl(linkText, opts)},
+ end: labelClose + 1,
+ };
+ }
+ // No match — fall back to a shortcut `[text]` (CommonMark back-off),
+ // leaving the trailing `[label]` to be parsed separately.
+ }
+ }
+ // Shortcut: `[text]`.
+ if (linkText.trim() === '') {
+ return null;
+ }
+ const href = linkDefs.get(normalizeLinkLabel(linkText));
+ if (href == null) {
+ return null;
+ }
+ return {
+ node: {type: 'link', href, children: parseInlineImpl(linkText, opts)},
+ end: textClose + 1,
+ };
+}
+
+/** Reference-image equivalent of {@link matchReferenceLink} (`![alt][label]`). */
+function matchReferenceImage(
+ text: string,
+ start: number,
+ linkDefs: ReadonlyMap<string, string>,
+): {node: InlineNode; end: number} | null {
+ const altClose = text.indexOf(']', start + 2);
+ if (altClose === -1) {
+ return null;
+ }
+ const alt = text.slice(start + 2, altClose);
+ if (text[altClose + 1] === '[') {
+ const labelClose = text.indexOf(']', altClose + 2);
+ if (labelClose !== -1) {
+ const rawLabel = text.slice(altClose + 2, labelClose);
+ const label = rawLabel === '' ? alt : rawLabel;
+ const src = linkDefs.get(normalizeLinkLabel(label));
+ if (src != null) {
+ return {node: {type: 'image', src, alt}, end: labelClose + 1};
+ }
+ // No match — fall back to a shortcut `![alt]`.
+ }
+ }
+ if (alt.trim() === '') {
+ return null;
+ }
+ const src = linkDefs.get(normalizeLinkLabel(alt));
+ if (src == null) {
+ return null;
+ }
+ return {node: {type: 'image', src, alt}, end: altClose + 1};
+}
+
// ---------------------------------------------------------------------------
// Inline parser helpers
// ---------------------------------------------------------------------------
@@ -260,6 +489,16 @@ function parseInlineImpl(text: string, opts: ResolvedOptions): InlineNode[] {
}
}
+ // --- Reference image ![alt][label] / ![alt][] / ![alt] ---
+ if (opts.linkDefs != null && text[i] === '!' && text[i + 1] === '[') {
+ const ref = matchReferenceImage(text, i, opts.linkDefs);
+ if (ref) {
+ nodes.push(ref.node);
+ i = ref.end;
+ continue;
+ }
+ }
+
// --- Citation: bracket [id] (before link — link requires `(` after `]`) ---
{
const citation = matchBracketCitation(text, i, opts);
@@ -287,6 +526,16 @@ function parseInlineImpl(text: string, opts: ResolvedOptions): InlineNode[] {
}
}
+ // --- Reference link [text][label] / [text][] / [text] ---
+ if (opts.linkDefs != null && text[i] === '[') {
+ const ref = matchReferenceLink(text, i, opts.linkDefs, opts);
+ if (ref) {
+ nodes.push(ref.node);
+ i = ref.end;
+ continue;
+ }
+ }
+
// --- Bold-italic: *** or ___ ---
if (
(text[i] === '*' && text[i + 1] === '*' && text[i + 2] === '*') ||
@@ -971,8 +1220,30 @@ export function parseMarkdown(
return parseMarkdownImpl(input, resolveOptions(arg));
}
-function parseMarkdownImpl(input: string, opts: ResolvedOptions): BlockNode[] {
- const lines = input.split('\n');
+function parseMarkdownImpl(
+ input: string,
+ baseOpts: ResolvedOptions,
+): BlockNode[] {
+ // Collect this input's link reference definitions and strip their lines,
+ // then merge them with any definitions inherited from an enclosing parse
+ // (the incremental parser passes the whole document's definitions in; a
+ // recursive blockquote/list parse inherits the outer definitions). Inherited
+ // definitions win on conflict, matching CommonMark's first-definition-wins
+ // in document order; locally-nested definitions still resolve within this
+ // parse.
+ const {defs, cleaned} = extractLinkDefinitions(input);
+ const inherited = baseOpts.linkDefs;
+ let linkDefs: ReadonlyMap<string, string> | undefined;
+ if (defs.size === 0) {
+ linkDefs = inherited;
+ } else if (inherited == null) {
+ linkDefs = defs;
+ } else {
+ linkDefs = new Map<string, string>([...defs, ...inherited]);
+ }
+ const opts: ResolvedOptions =
+ linkDefs != null ? {...baseOpts, linkDefs} : baseOpts;
+ const lines = cleaned.split('\n');
const blocks: BlockNode[] = [];
let index = 0;
@@ -1106,6 +1377,13 @@ export interface IncrementalState {
* with newly-arriving content.
*/
autolink?: 'gfm';
+ /**
+ * Signature of the link reference definitions the cached `settledBlocks`
+ * were parsed with. Definitions are document-global and typically arrive
+ * (in a footer) after the references that use them, so when the set changes
+ * the settled cache is invalidated to let earlier references resolve.
+ */
+ linkDefsKey?: string;
}
export function createIncrementalState(): IncrementalState {
@@ -1434,16 +1712,33 @@ export function parseMarkdownIncremental(
state.settledText = '';
state.settledBlocks = [];
state.settledUpTo = 0;
+ state.linkDefsKey = undefined;
return [];
}
+ // Link reference definitions are document-global and usually stream in
+ // (as a footer) after the references that use them, so collect them from the
+ // whole input and pass them into every slice parse. When the set changes,
+ // invalidate the settled cache so already-settled references re-resolve.
+ const {defs: linkDefs} = extractLinkDefinitions(input);
+ const linkDefsKey = linkDefsSignature(linkDefs);
+ if (state.linkDefsKey !== linkDefsKey) {
+ state.prevInput = '';
+ state.settledText = '';
+ state.settledBlocks = [];
+ state.settledUpTo = 0;
+ state.linkDefsKey = linkDefsKey;
+ }
+ const parseOpts: ResolvedOptions =
+ linkDefs.size > 0 ? {...opts, linkDefs} : opts;
+
const lines = input.split('\n');
const boundary = findSettledBoundary(lines);
if (boundary < 0) {
// Inside an unclosed fence or no blank-line boundary — full re-parse
state.prevInput = input;
- return parseMarkdownImpl(input, opts);
+ return parseMarkdownImpl(input, parseOpts);
}
const settledText = lines.slice(0, boundary).join('\n');
@@ -1461,15 +1756,15 @@ export function parseMarkdownIncremental(
) {
// Settled portion grew — parse only the new delta
const delta = settledText.slice(state.settledText.length);
- const deltaBlocks = parseMarkdownImpl(delta, opts);
+ const deltaBlocks = parseMarkdownImpl(delta, parseOpts);
settledBlocks = mergeSettledBlocks(state.settledBlocks, deltaBlocks);
} else {
// Content before the boundary changed — full re-parse of settled portion
- settledBlocks = parseMarkdownImpl(settledText, opts);
+ settledBlocks = parseMarkdownImpl(settledText, parseOpts);
}
const unsettledBlocks = unsettledText
- ? parseMarkdownImpl(unsettledText, opts)
+ ? parseMarkdownImpl(unsettledText, parseOpts)
: [];
state.settledText = settledText;