Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): parse table-escaped wiki alias separators (PRD-7965) (#4535)

Nick Gomezf054db62fc36
diff --git a/.changeset/wiki-escaped-alias-separator.md b/.changeset/wiki-escaped-alias-separator.md
new file mode 100644
index 000000000..097f02e3c
--- /dev/null
+++ b/.changeset/wiki-escaped-alias-separator.md
@@ -0,0 +1,5 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Wiki links and embeds written with an escaped alias separator (`[[Page\|Alias]]`, required inside tables) now resolve to a clean target, anchor, and alias instead of one ending in a stray backslash; the escape you authored stays in the file. Escape-only or whitespace targets are no longer links.
diff --git a/docs/content/features/assets-and-embeds.mdx b/docs/content/features/assets-and-embeds.mdx
index 9b0146c58..a91845d7c 100644
--- a/docs/content/features/assets-and-embeds.mdx
+++ b/docs/content/features/assets-and-embeds.mdx
@@ -18,7 +18,7 @@ AI agents add assets through the MCP [`write`](/docs/reference/mcp) tool's `asse
- **Video and audio render native players.** The video block also takes YouTube, Vimeo, and Loom URLs and renders each host's own player.
- **PDFs and other documents** (`.docx`, `.zip`, `.csv`, …) insert a file attachment row — icon, name, size — linking to the file. To render pages in the doc, use the **PDF** block instead: a multi-page viewer with thumbnails, page navigation, and zoom; set `page=3` in its `anchor` setting to open at that page.
-In the markdown source, dropped media serializes as `<img>` / `<video>` / `<audio>` and file attachments as wiki-style embeds (`![[report.pdf]]`). You can author the wiki form directly: `![[diagram.png]]` on its own line follows the type rules above, inside a sentence it stays a link, and a fragment (`![[report.pdf#page=3]]`) is preserved on the rendered link. Standard `![alt](./chart.png)` image syntax works too.
+In the markdown source, dropped media serializes as `<img>` / `<video>` / `<audio>` and file attachments as wiki-style embeds (`![[report.pdf]]`). You can author the wiki form directly: `![[diagram.png]]` on its own line follows the type rules above, inside a sentence it stays a link, a fragment (`![[report.pdf#page=3]]`) is preserved on the rendered link, and an alias on an image embed sets its alt text (`![[diagram.png|Diagram]]`). Standard `![alt](./chart.png)` image syntax works too. Inside a table cell, escape the alias separator: `![[diagram.png\|Diagram]]` resolves identically to the unescaped form. Byte-for-byte preservation has narrow exceptions, none of them reached by authoring the escape — see [Tables](/docs/features/editor#tables) for what they are.
## Embedding web pages
diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdx
index aacb8d937..f697a908c 100644
--- a/docs/content/features/editor.mdx
+++ b/docs/content/features/editor.mdx
@@ -52,6 +52,8 @@ To reorder with the keyboard, place the cursor in an item or select several neig
Insert a table from the slash menu. The header row stays visible as you scroll down a long table, the first column stays pinned as you scroll sideways, and dragging a row or column handle reorders it. Cells are single-line in the stored markdown: pressing Enter inside a cell — or pasting a table whose cells hold lists or paragraphs — joins the lines with `<br />`, the GFM line-break idiom, so the table stays valid for everyone else opening the file. `<br>` tags in existing files render as real line breaks and round-trip byte-for-byte.
+Aliased wiki links and embeds must escape their separator inside a table cell: write it as `\|`, since a bare `|` ends the cell. `[[Page\|alias]]` in a cell resolves identically to `[[Page|alias]]` outside one, and the escape you author is preserved in the saved file. Two corners escape that preservation, and only the first is about cells. In a cell of any table rather than only a migrated one, a code span or raw HTML whose own content holds a backslash immediately before a pipe gains a second backslash on save. That extra backslash stops the pipe from reading as an escape, so the cell ends at that pipe and the value is cut in two. OpenKnowledge then shows the tail as an extra cell in that row, or stops parsing the block as a table when the affected cell is in the header row; other readers differ on the same bytes, and some drop the tail instead of showing it — so treat anything after that pipe as at risk rather than merely misplaced. The second corner is not a table phenomenon and does not strike on save: an aliased wiki link or embed whose alias holds that same pair, anywhere in a document, is written to the file with the backslash intact and comes back without it the next time the file is opened. Nothing is cut in two and no row breaks, so the only cue is the alias itself reading `a|b` where you wrote `a\|b`. Neither corner is reachable by writing the source: both arrive by pasting, or by editing the cell or the alias in place. Writing `\|` as an alias separator, or inside a code span in a cell, stays the correct form and is preserved as authored.
+
### Mermaid diagrams
A `mermaid` code fence renders as a live diagram (the slash menu can insert one). On-diagram buttons pan, zoom, and reset the view; mouse-wheel zooming and drag panning are disabled so a large diagram never moves while you scroll past it.
diff --git a/docs/content/migrate/obsidian.mdx b/docs/content/migrate/obsidian.mdx
index 6c49b9a64..157813c6d 100644
--- a/docs/content/migrate/obsidian.mdx
+++ b/docs/content/migrate/obsidian.mdx
@@ -30,7 +30,7 @@ Most of what you write in Obsidian renders and round-trips in OpenKnowledge unch
| Obsidian syntax | Example | In OpenKnowledge |
| --- | --- | --- |
-| Wiki links | `[[Page]]`, `[[Page\|alias]]`, `[[Page#Heading]]` | Resolved to the target doc; feed backlinks and the graph. Preserved as written. |
+| Wiki links | `[[Page]]`, `[[Page\|alias]]`, `[[Page#Heading]]` | Resolved to the target doc; feed backlinks and the graph. Preserved as written. Inside a table cell, escape the alias separator (see below). |
| Markdown links | `[text](./page.md)` | Fully supported and the [recommended form](/docs/reference/core-concepts#links-and-backlinks) for new links. Wiki links keep working as a superset. |
| YAML frontmatter | `---` block at the top | Open-shape — any keys. `aliases`, `tags`, `cssclasses`, dates, and lists are preserved. Edit them in the [Properties panel](/docs/features/editor#properties). |
| Tags | `#tag`, or `tags:` in frontmatter | Both forms are indexed and searchable. |
@@ -42,6 +42,8 @@ Most of what you write in Obsidian renders and round-trips in OpenKnowledge unch
| Footnotes | `[^1]` with `[^1]: …` | Supported, including named footnotes. |
| Asset embeds | `![[image.png]]`, `![[file.pdf#page=3]]` | Images and PDFs render inline. See [Assets and embeds](/docs/features/assets-and-embeds). |
+Inside a table cell, an aliased wiki link or embed has to escape its separator as `\|`, because a bare `|` ends the cell: the cell form is `[[Page\|alias]]`, or `![[image.png\|alt]]` for embeds. Each literal `|` inside the alias carries its own backslash too, so an alias like `Some | Alias` is written `[[Page\|Some \| Alias]]` in a cell, or `![[image.png\|Some \| Alias]]` as an embed. The escaped form resolves identically to the unescaped one, and the escape you author stays in the file. A target that is only whitespace or only the escape (`[[ ]]`, `[[\|alias]]`) is not a link. Byte-for-byte preservation has narrow exceptions, none of them reached by authoring the escape — see [Tables](/docs/features/editor#tables) for what they are.
+
## Where the two differ
A handful of Obsidian features are not supported, or behave differently. None of them corrupt your files — the syntax is preserved on disk; it just isn't interpreted the same way.
diff --git a/packages/core/schema-snapshot.json b/packages/core/schema-snapshot.json
index a507ba31b..fc0f4837e 100644
--- a/packages/core/schema-snapshot.json
+++ b/packages/core/schema-snapshot.json
@@ -793,10 +793,22 @@
"hasDefault": true,
"default": "noopener noreferrer"
},
+ "sourceAlias": {
+ "hasDefault": true,
+ "default": null
+ },
+ "sourceAnchor": {
+ "hasDefault": true,
+ "default": null
+ },
"sourceForm": {
"hasDefault": true,
"default": null
},
+ "sourceTarget": {
+ "hasDefault": true,
+ "default": null
+ },
"sourceTitleMarker": {
"hasDefault": true,
"default": null
diff --git a/packages/core/src/extensions/link-fidelity.ts b/packages/core/src/extensions/link-fidelity.ts
index 7b6ae485f..b7a81cf25 100644
--- a/packages/core/src/extensions/link-fidelity.ts
+++ b/packages/core/src/extensions/link-fidelity.ts
@@ -58,6 +58,9 @@ export const LinkFidelity = Link.extend({
alias: { default: null, rendered: false },
sourceUrlForm: { default: null, rendered: false },
sourceTitleMarker: { default: null, rendered: false },
+ sourceTarget: { default: null, rendered: false },
+ sourceAnchor: { default: null, rendered: false },
+ sourceAlias: { default: null, rendered: false },
};
},
});
diff --git a/packages/core/src/extensions/wiki-link.test.ts b/packages/core/src/extensions/wiki-link.test.ts
index ea403b110..b4b0167fe 100644
--- a/packages/core/src/extensions/wiki-link.test.ts
+++ b/packages/core/src/extensions/wiki-link.test.ts
@@ -1,3 +1,4 @@
+import type { JSONContent } from '@tiptap/core';
import { getSchema } from '@tiptap/core';
import { describe, expect, test } from 'vitest';
import { MarkdownManager } from '../markdown/index.ts';
@@ -41,6 +42,85 @@ describe('parseWikiLink', () => {
});
});
+describe('parseWikiLink: escaped alias separator', () => {
+ test('escaped separator after an anchor leaves the anchor clean', () => {
+ expect(
+ parseWikiLink(String.raw`[[targets/existing-page#details\|Wiki alias to details]]`),
+ ).toEqual({
+ type: 'wikilink',
+ raw: String.raw`[[targets/existing-page#details\|Wiki alias to details]]`,
+ target: 'targets/existing-page',
+ anchor: 'details',
+ alias: 'Wiki alias to details',
+ });
+ });
+
+ test('escaped separator with no anchor leaves the target clean', () => {
+ expect(parseWikiLink(String.raw`[[https://inkeep.com\|External wiki link]]`)).toEqual({
+ type: 'wikilink',
+ raw: String.raw`[[https://inkeep.com\|External wiki link]]`,
+ target: 'https://inkeep.com',
+ anchor: null,
+ alias: 'External wiki link',
+ });
+ });
+
+ test('escaped pipe folded into the alias unescapes', () => {
+ expect(parseWikiLink(String.raw`[[a\|b\|c]]`)).toEqual({
+ type: 'wikilink',
+ raw: String.raw`[[a\|b\|c]]`,
+ target: 'a',
+ anchor: null,
+ alias: 'b|c',
+ });
+ });
+
+ test('an escaped separator after an anchor with an empty anchor drops the anchor', () => {
+ expect(parseWikiLink(String.raw`[[Page#\|Alias]]`)).toEqual({
+ type: 'wikilink',
+ raw: String.raw`[[Page#\|Alias]]`,
+ target: 'Page',
+ anchor: null,
+ alias: 'Alias',
+ });
+ });
+
+ test('a target that is only the separator escape rejects', () => {
+ expect(parseWikiLink(String.raw`[[\|alias]]`)).toBeNull();
+ expect(parseWikiLink(String.raw`[[ \|alias]]`)).toBeNull();
+ });
+
+ test('a backslash not at the separator boundary stays literal', () => {
+ expect(parseWikiLink(String.raw`[[a\b|Alias]]`)).toMatchObject({
+ target: String.raw`a\b`,
+ alias: 'Alias',
+ });
+ });
+
+ test('a trailing backslash with no alias stays literal', () => {
+ expect(parseWikiLink(String.raw`[[a\]]`)).toEqual({
+ type: 'wikilink',
+ raw: String.raw`[[a\]]`,
+ target: 'a\\',
+ anchor: null,
+ alias: null,
+ });
+ });
+
+ test('unescaped separators keep parsing as before', () => {
+ expect(parseWikiLink('[[targets/existing-page#details|Wiki alias to details]]')).toMatchObject({
+ target: 'targets/existing-page',
+ anchor: 'details',
+ alias: 'Wiki alias to details',
+ });
+ expect(parseWikiLink('[[https://inkeep.com|External wiki link]]')).toMatchObject({
+ target: 'https://inkeep.com',
+ anchor: null,
+ alias: 'External wiki link',
+ });
+ });
+});
+
describe('wikiLink helpers', () => {
test('normalizes nullable strings', () => {
expect(normalizeNullableString(' Alias ')).toBe('Alias');
@@ -59,6 +139,26 @@ describe('wikiLink helpers', () => {
);
});
+ test('escapes a pipe inside the alias so the rendered form re-parses losslessly: renderWikiLink is destination-agnostic and escapes every pipe the moment the alias contains one, while destination-aware table-cell emit belongs to the serializer', () => {
+ const rendered = renderWikiLink({ target: 'Page', alias: 'a|b', anchor: null });
+ expect(rendered).toBe('[[Page\\|a\\|b]]');
+ expect(parseWikiLink(rendered)?.target).toBe('Page');
+ expect(parseWikiLink(rendered)?.alias).toBe('a|b');
+ const row = `| L |\n| --- |\n| ${rendered} |`;
+ expect(mdManager.serialize(mdManager.parse(row)).trim()).toBe(row);
+ });
+
+ test('an alias whose own value carries a backslash before a pipe escapes the pipe and leaves the backslash literal, so the decoded rule and a parity-aware one are observably different here, and the even backslash run this leaves is not cell-safe: no form is both byte-exact and cell-safe for this value, so a cell must go through the serializer rather than inherit this output', () => {
+ const rendered = renderWikiLink({ target: 'Page', alias: String.raw`a\|b`, anchor: null });
+ expect(rendered).toBe(String.raw`[[Page\|a\\|b]]`);
+ expect(parseWikiLink(rendered)?.alias).toBe(String.raw`a\|b`);
+
+ const row = `| L |\n| --- |\n| ${rendered} |`;
+ const inCell = mdManager.serialize(mdManager.parse(row)).trim();
+ expect(inCell).not.toBe(row);
+ expect(inCell).toBe(`| L | |\n| --- | - |\n| [[Page\\|a\\\\ | b]] |`);
+ });
+
test('prefers alias as display text', () => {
expect(getWikiLinkText({ target: 'Page', alias: 'Alias', anchor: 'Heading' })).toBe('Alias');
expect(getWikiLinkText({ target: 'Page', alias: null, anchor: 'Heading' })).toBe(
@@ -96,3 +196,159 @@ describe('wikiLink round-trip', () => {
});
}
});
+
+describe('wikiLink PM round-trip with escaped alias separators', () => {
+ const fixtures = [
+ String.raw`[[targets/existing-page#details\|Wiki alias to details]]`,
+ String.raw`[[https://inkeep.com\|External wiki link]]`,
+ String.raw`[[a\|b\|c]]`,
+ String.raw`![[Attachments/pic.png\|Alt text]]`,
+ String.raw`![[file.pdf#page=3\|Page 3]]`,
+ String.raw`[[Page#\|Alias]]`,
+ String.raw`![[Page#\|Alt]]`,
+ String.raw`[[Page\| ]]`,
+ String.raw`[[Page#head\| ]]`,
+ String.raw`![[Page\| ]]`,
+ '[[Page#Heading|Alias]]',
+ '[[ Page # Heading | Alias ]]',
+ ];
+
+ for (const original of fixtures) {
+ test(original, () => {
+ expect(mdManager.serialize(mdManager.parse(`${original}\n`)).trim()).toBe(original);
+ });
+ }
+});
+
+describe('an alias edited to hold a backslash before a pipe keeps the backslash on disk and loses it on the next open', () => {
+ const findWikiLinkNode = (node: JSONContent): JSONContent | null => {
+ if (node.type === 'wikiLink') return node;
+ for (const child of node.content ?? []) {
+ const found = findWikiLinkNode(child);
+ if (found) return found;
+ }
+ return null;
+ };
+
+ const findEmbedTextNode = (node: JSONContent): JSONContent | null => {
+ if (node.marks?.some((mark) => mark.attrs?.sourceForm === 'wikiembed')) return node;
+ for (const child of node.content ?? []) {
+ const found = findEmbedTextNode(child);
+ if (found) return found;
+ }
+ return null;
+ };
+
+ const parseCopy = (source: string): JSONContent =>
+ JSON.parse(JSON.stringify(mdManager.parse(source))) as JSONContent;
+
+ const emitEditedWikiLinkAlias = (source: string, alias: string): string => {
+ const doc = parseCopy(source);
+ const node = findWikiLinkNode(doc);
+ if (!node?.attrs) throw new Error('expected a wikiLink node with attrs in the parsed source');
+ node.attrs.alias = alias;
+ node.attrs.sourceTarget = null;
+ node.attrs.sourceAlias = null;
+ return mdManager.serialize(doc);
+ };
+
+ const emitEditedEmbedAlias = (source: string, alias: string): string => {
+ const doc = parseCopy(source);
+ const text = findEmbedTextNode(doc);
+ const mark = text?.marks?.find((m) => m.attrs?.sourceForm === 'wikiembed');
+ if (!text || !mark?.attrs) throw new Error('expected an embed link mark in the parsed source');
+ mark.attrs.alias = alias;
+ mark.attrs.sourceTarget = null;
+ mark.attrs.sourceAlias = null;
+ text.text = alias;
+ return mdManager.serialize(doc);
+ };
+
+ const reparsedWikiLinkAlias = (markdown: string): unknown =>
+ findWikiLinkNode(parseCopy(markdown))?.attrs?.alias;
+
+ const reparsedEmbedAlias = (markdown: string): unknown =>
+ findEmbedTextNode(parseCopy(markdown))?.marks?.find((m) => m.attrs?.sourceForm === 'wikiembed')
+ ?.attrs?.alias;
+
+ test('a wiki link in a table cell keeps the row and writes the backslash, then reads back without it', () => {
+ const emitted = emitEditedWikiLinkAlias(
+ '| L |\n| --- |\n| [[Page\\|plain]] |\n',
+ String.raw`a\|b`,
+ );
+ expect(emitted).toBe('| L |\n| --- |\n| [[Page\\|a\\|b]] |\n');
+ expect(emitted).toContain(String.raw`a\|b`);
+ expect(findWikiLinkNode(parseCopy(emitted))?.attrs?.target).toBe('Page');
+ expect(reparsedWikiLinkAlias(emitted)).toBe('a|b');
+ });
+
+ test('a wiki link outside a cell keeps a bare separator and loses the backslash the same way', () => {
+ const emitted = emitEditedWikiLinkAlias('[[Page\\|plain]]\n', String.raw`a\|b`);
+ expect(emitted).toBe('[[Page|a\\|b]]\n');
+ expect(reparsedWikiLinkAlias(emitted)).toBe('a|b');
+ });
+
+ test('an embed in a table cell behaves the same, reached through its link mark rather than a node type', () => {
+ const emitted = emitEditedEmbedAlias(
+ '| L |\n| --- |\n| ![[pic.png\\|alt]] |\n',
+ String.raw`a\|b`,
+ );
+ expect(emitted).toBe('| L |\n| --- |\n| ![[pic.png\\|a\\|b]] |\n');
+ expect(reparsedEmbedAlias(emitted)).toBe('a|b');
+ });
+
+ test('an embed outside a cell loses the backslash the same way', () => {
+ const emitted = emitEditedEmbedAlias('see ![[pic.png\\|alt]] here\n', String.raw`a\|b`);
+ expect(emitted).toBe('see ![[pic.png|a\\|b]] here\n');
+ expect(reparsedEmbedAlias(emitted)).toBe('a|b');
+ });
+});
+
+describe('wiki tables with escaped alias separators round-trip byte-for-byte', () => {
+ const fixtures = [
+ '| Link |\n| --- |\n| [[target\\|Friendly label]] |',
+ '| L |\n| --- |\n| [[Page#sec\\|Alias]] |',
+ '| Asset |\n| --- |\n| ![[photo.png\\|caption]] |',
+ '| L |\n| --- |\n| [[Page#\\|Alias]] |',
+ '| A |\n| --- |\n| ![[Page#\\|Alt]] |',
+ '| L |\n| --- |\n| [[Page\\| ]] |',
+ ];
+
+ for (const original of fixtures) {
+ test(original, () => {
+ expect(mdManager.serialize(mdManager.parse(`${original}\n`)).trim()).toBe(original);
+ });
+ }
+});
+
+describe('inline embeds with escaped alias separators round-trip through the link mark', () => {
+ const fixtures = [
+ 'see ![[pic.png\\|alt]] here',
+ 'see ![[file.pdf#page=3\\|Page 3]] here',
+ 'see ![[Page#\\|Alt]] here',
+ '| see ![[pic.png\\|alt]] here |\n| --- |\n| x |',
+ ];
+
+ for (const original of fixtures) {
+ test(original, () => {
+ expect(mdManager.serialize(mdManager.parse(`${original}\n`)).trim()).toBe(original);
+ });
+ }
+
+ test('an inline embed parses to the link-mark representation, not a component', () => {
+ const pmNode = schema.nodeFromJSON(mdManager.parse('see ![[pic.png\\|alt]] here\n'));
+ const linkMarks: Array<Record<string, unknown>> = [];
+ pmNode.descendants((child) => {
+ for (const mark of child.marks) {
+ if (mark.type.name === 'link') linkMarks.push({ ...mark.attrs });
+ }
+ });
+ expect(linkMarks).toHaveLength(1);
+ expect(linkMarks[0]).toMatchObject({
+ sourceForm: 'wikiembed',
+ target: 'pic.png',
+ sourceTarget: 'pic.png\\',
+ alias: 'alt',
+ });
+ });
+});
diff --git a/packages/core/src/extensions/wiki-link.ts b/packages/core/src/extensions/wiki-link.ts
index 14cfed229..fe63b53d2 100644
--- a/packages/core/src/extensions/wiki-link.ts
+++ b/packages/core/src/extensions/wiki-link.ts
@@ -1,4 +1,8 @@
import { Node } from '@tiptap/core';
+import {
+ escapeDecodedTableCellPipes,
+ normalizeWikiSeparatorEscapes,
+} from '../markdown/wiki-escape.ts';
import { renderInlineObjectText } from './input-rule-text.ts';
export interface WikiLinkAttrs {
@@ -26,15 +30,22 @@ export function parseWikiLink(src: string): {
const match = src.match(WIKI_LINK_PATTERN);
if (!match) return null;
- const target = match[1]?.trim() ?? '';
+ const { target, anchor, alias } = normalizeWikiSeparatorEscapes(
+ {
+ target: match[1]?.trim() ?? '',
+ anchor: normalizeNullableString(match[2]),
+ alias: normalizeNullableString(match[3]),
+ },
+ { separatorCrossed: match[3] !== undefined },
+ );
if (!target) return null;
return {
type: 'wikilink',
raw: match[0],
target,
- anchor: normalizeNullableString(match[2]),
- alias: normalizeNullableString(match[3]),
+ anchor,
+ alias,
};
}
@@ -51,7 +62,9 @@ export function renderWikiLink(attrs: Pick<WikiLinkAttrs, 'target' | 'alias' | '
}
if (attrs.alias) {
- rendered += `|${attrs.alias}`;
+ rendered += attrs.alias.includes('|')
+ ? `\\|${escapeDecodedTableCellPipes(attrs.alias)}`
+ : `|${attrs.alias}`;
}
return `${rendered}]]`;
diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts
index 989c992e4..a6cd6ad58 100644
--- a/packages/core/src/index.ts
+++ b/packages/core/src/index.ts
@@ -1034,6 +1034,12 @@ export {
INLINE_TAG_VALUE_RE,
TAG_IN_TEXT_PATTERN_SOURCE,
} from './markdown/tag-promotion.ts';
+export {
+ type CleanWikiSegments,
+ normalizeWikiSeparatorEscapes,
+ rawSegmentOr,
+ type WikiSegmentKind,
+} from './markdown/wiki-escape.ts';
export {
getParseHealth,
incrementBlockFallback,
diff --git a/packages/core/src/markdown/index.ts b/packages/core/src/markdown/index.ts
index 541168f5a..cc8bd67e6 100644
--- a/packages/core/src/markdown/index.ts
+++ b/packages/core/src/markdown/index.ts
@@ -871,6 +871,9 @@ function buildMdastToPmHandlers(
const target = node.data?.target ?? '';
const alias = node.data?.alias ?? null;
const anchor = node.data?.anchor ?? null;
+ const sourceTarget = node.data?.sourceTarget ?? null;
+ const sourceAnchor = node.data?.sourceAnchor ?? null;
+ const sourceAlias = node.data?.sourceAlias ?? null;
const ext = extensionOf(target);
const { resolveEmbed, sourcePath } = parseCtx.current;
const resolved =
@@ -895,7 +898,16 @@ function buildMdastToPmHandlers(
attributes: [],
sourceRaw: '',
sourceDirty: false,
- props: { src: srcOrTarget, alt: alias ?? target, target, anchor, alias },
+ props: {
+ src: srcOrTarget,
+ alt: alias ?? target,
+ target,
+ anchor,
+ alias,
+ sourceTarget,
+ sourceAnchor,
+ sourceAlias,
+ },
});
}
if (
@@ -910,7 +922,16 @@ function buildMdastToPmHandlers(
attributes: [],
sourceRaw: '',
sourceDirty: false,
- props: { src: srcOrTarget, title: alias ?? target, target, anchor, alias },
+ props: {
+ src: srcOrTarget,
+ title: alias ?? target,
+ target,
+ anchor,
+ alias,
+ sourceTarget,
+ sourceAnchor,
+ sourceAlias,
+ },
});
}
if (
@@ -925,7 +946,16 @@ function buildMdastToPmHandlers(
attributes: [],
sourceRaw: '',
sourceDirty: false,
- props: { src: srcOrTarget, title: alias ?? target, target, anchor, alias },
+ props: {
+ src: srcOrTarget,
+ title: alias ?? target,
+ target,
+ anchor,
+ alias,
+ sourceTarget,
+ sourceAnchor,
+ sourceAlias,
+ },
});
}
if (
@@ -944,7 +974,16 @@ function buildMdastToPmHandlers(
attributes: [],
sourceRaw: '',
sourceDirty: false,
- props: { src: srcOrTarget, target, anchor, alias, size },
+ props: {
+ src: srcOrTarget,
+ target,
+ anchor,
+ alias,
+ size,
+ sourceTarget,
+ sourceAnchor,
+ sourceAlias,
+ },
});
}
@@ -959,6 +998,9 @@ function buildMdastToPmHandlers(
target,
anchor,
alias,
+ sourceTarget,
+ sourceAnchor,
+ sourceAlias,
});
return schema.text(label, [linkMark]);
}
@@ -1569,6 +1611,12 @@ function buildPmToMdastHandlers(
typeof mark.attrs.alias === 'string' && mark.attrs.alias.length > 0
? mark.attrs.alias
: null;
+ const sourceTarget: string | null =
+ typeof mark.attrs.sourceTarget === 'string' ? mark.attrs.sourceTarget : null;
+ const sourceAnchor: string | null =
+ typeof mark.attrs.sourceAnchor === 'string' ? mark.attrs.sourceAnchor : null;
+ const sourceAlias: string | null =
+ typeof mark.attrs.sourceAlias === 'string' ? mark.attrs.sourceAlias : null;
let label = alias ? alias : anchor ? `${target}#${anchor}` : target;
const visibleText = children
.map((child) => ('value' in child && typeof child.value === 'string' ? child.value : ''))
@@ -1580,7 +1628,7 @@ function buildPmToMdastHandlers(
return {
type: 'wikiLinkEmbed' as const,
value: label,
- data: { target, anchor, alias },
+ data: { target, anchor, alias, sourceTarget, sourceAnchor, sourceAlias },
children: [{ type: 'text' as const, value: label }],
} as unknown as MdastNodes;
}
diff --git a/packages/core/src/markdown/table-cell-flatten.ts b/packages/core/src/markdown/table-cell-flatten.ts
index 48a434f4e..e009d4471 100644
--- a/packages/core/src/markdown/table-cell-flatten.ts
+++ b/packages/core/src/markdown/table-cell-flatten.ts
@@ -1,5 +1,6 @@
import type { Html, List, Nodes, PhrasingContent, Root, TableCell } from 'mdast';
import { visit } from 'unist-util-visit';
+import { escapeDecodedTableCellPipes } from './wiki-escape.ts';
const CELL_PHRASING_TYPES: ReadonlySet<string> = new Set([
'break',
@@ -37,7 +38,7 @@ function normalizeCellValueNodes(node: { children?: Nodes[] }): void {
child.value = child.value.replace(/[ \t]*\n[ \t]*/g, ' ');
}
if (child.type === 'html' && child.value.includes('|')) {
- child.value = child.value.replace(/\|/g, '\\|');
+ child.value = escapeDecodedTableCellPipes(child.value);
}
}
normalizeCellValueNodes(child as { children?: Nodes[] });
diff --git a/packages/core/src/markdown/to-markdown-handlers.ts b/packages/core/src/markdown/to-markdown-handlers.ts
index 80479bdf2..102e6b632 100644
--- a/packages/core/src/markdown/to-markdown-handlers.ts
+++ b/packages/core/src/markdown/to-markdown-handlers.ts
@@ -8,6 +8,7 @@ import { widenFenceLength } from './code-fence.ts';
import type { RawMdxFallbackMdast } from './mdast-augmentation.ts';
import { TO_MARKDOWN_EXT } from './remark-mdx-agnostic.ts';
import { isInlineWhitespaceNumericCharRef } from './whitespace-char-ref.ts';
+import { escapeDecodedTableCellPipes } from './wiki-escape.ts';
declare module 'mdast-util-to-markdown' {
interface ConstructNameMap {
@@ -351,7 +352,7 @@ export const toMarkdownHandlers = {
}
const span = `${fence}${value}${fence}`;
- return state.stack.includes('tableCell') ? span.replace(/\|/g, '\\$&') : span;
+ return state.stack.includes('tableCell') ? escapeDecodedTableCellPipes(span) : span;
},
inlineMath: inlineMathHandler,
diff --git a/packages/core/src/markdown/wiki-escape.ts b/packages/core/src/markdown/wiki-escape.ts
new file mode 100644
index 000000000..39a23d144
--- /dev/null
+++ b/packages/core/src/markdown/wiki-escape.ts
@@ -0,0 +1,81 @@
+export interface WikiSegments {
+ target: string;
+ anchor: string | null;
+ alias: string | null;
+}
+
+export type CleanWikiSegments = WikiSegments;
+
+export function normalizeWikiSeparatorEscapes(
+ segments: WikiSegments,
+ options: { separatorCrossed: boolean },
+): CleanWikiSegments {
+ const { target, anchor, alias } = segments;
+ if (!options.separatorCrossed) return segments;
+ if (anchor !== null) {
+ const strippedAnchor = stripTrailingBackslash(anchor);
+ return {
+ target,
+ anchor: strippedAnchor.length > 0 ? strippedAnchor : null,
+ alias: alias === null ? null : unescapePipes(alias),
+ };
+ }
+ return {
+ target: stripTrailingBackslash(target),
+ anchor: null,
+ alias: alias === null ? null : unescapePipes(alias),
+ };
+}
+
+export type WikiSegmentKind = 'separatorAdjacent' | 'alias';
+
+export function rawSegmentMatchesValue(
+ raw: string,
+ current: string,
+ kind: WikiSegmentKind,
+): boolean {
+ const trimmed = raw.trim();
+ if (trimmed === current) return true;
+ return kind === 'alias'
+ ? unescapePipes(trimmed) === current
+ : stripTrailingBackslash(trimmed) === current;
+}
+
+export function rawSegmentOr(
+ raw: string | null | undefined,
+ current: string,
+ kind: WikiSegmentKind,
+): string {
+ return typeof raw === 'string' && rawSegmentMatchesValue(raw, current, kind) ? raw : current;
+}
+
+export function separatorEscapeLeavesEmpty(raw: string): boolean {
+ return stripTrailingBackslash(raw.trim()) === '';
+}
+
+function stripTrailingBackslash(segment: string): string {
+ return segment.endsWith('\\') ? segment.slice(0, -1) : segment;
+}
+
+function unescapePipes(alias: string): string {
+ return alias.replace(/\\\|/g, '|');
+}
+
+export function escapeTableCellPipes(value: string): string {
+ let out = '';
+ let backslashes = 0;
+ for (const ch of value) {
+ if (ch === '\\') {
+ backslashes++;
+ } else {
+ if (ch === '|' && backslashes % 2 === 0) out += '\\';
+ backslashes = 0;
+ }
+ out += ch;
+ }
+ return out;
+}
+
+export function escapeDecodedTableCellPipes(value: string): string {
+ return value.replace(/\|/g, '\\|');
+}
diff --git a/packages/core/src/markdown/wiki-link-micromark.ts b/packages/core/src/markdown/wiki-link-micromark.ts
index 3d46bf01c..ce7af4ea6 100644
--- a/packages/core/src/markdown/wiki-link-micromark.ts
+++ b/packages/core/src/markdown/wiki-link-micromark.ts
@@ -3,6 +3,12 @@ import type { Handle as ToMarkdownHandle } from 'mdast-util-to-markdown';
import type { Construct, Extension, State, Token, Tokenizer } from 'micromark-util-types';
import type { Processor } from 'unified';
import type { WikiLinkEmbedMdast, WikiLinkMdast } from './mdast-augmentation.ts';
+import {
+ escapeTableCellPipes,
+ normalizeWikiSeparatorEscapes,
+ rawSegmentOr,
+ separatorEscapeLeavesEmpty,
+} from './wiki-escape.ts';
declare module 'micromark-util-types' {
interface TokenTypeMap {
@@ -22,11 +28,19 @@ const CODE_LBRACKET = 91;
const CODE_RBRACKET = 93;
const CODE_PIPE = 124;
const CODE_HASH = 35;
+const CODE_VIRTUAL_SPACE = -1;
+const CODE_HORIZONTAL_TAB = -2;
+
+function characterForCode(code: number): string {
+ if (code === CODE_HORIZONTAL_TAB) return '\t';
+ if (code === CODE_VIRTUAL_SPACE) return ' ';
+ return String.fromCharCode(code);
+}
const tokenizeWikiLink: Tokenizer = (effects, ok, nok) => {
- let targetSize = 0;
let anchorSize = 0;
let aliasSize = 0;
+ let targetRaw = '';
return start;
@@ -50,12 +64,12 @@ const tokenizeWikiLink: Tokenizer = (effects, ok, nok) => {
if (code === null || code === -5 || code === -4 || code === -3) return nok(code);
if (code === CODE_LBRACKET) return nok(code);
if (code === CODE_RBRACKET) {
- if (targetSize === 0) return nok(code);
+ if (targetRaw.trim() === '') return nok(code);
effects.exit('wikiLinkTarget');
return close1(code);
}
if (code === CODE_HASH) {
- if (targetSize === 0) return nok(code);
+ if (targetRaw.trim() === '') return nok(code);
effects.exit('wikiLinkTarget');
effects.enter('wikiLinkSeparator');
effects.consume(code);
@@ -64,7 +78,7 @@ const tokenizeWikiLink: Tokenizer = (effects, ok, nok) => {
return anchor as State;
}
if (code === CODE_PIPE) {
- if (targetSize === 0) return nok(code);
+ if (separatorEscapeLeavesEmpty(targetRaw)) return nok(code);
effects.exit('wikiLinkTarget');
effects.enter('wikiLinkSeparator');
effects.consume(code);
@@ -73,7 +87,7 @@ const tokenizeWikiLink: Tokenizer = (effects, ok, nok) => {
return alias as State;
}
effects.consume(code);
- targetSize++;
+ targetRaw += characterForCode(code);
return target as State;
}
@@ -134,9 +148,9 @@ const wikiLinkConstruct: Construct = {
};
const tokenizeWikiLinkEmbed: Tokenizer = (effects, ok, nok) => {
- let targetSize = 0;
let anchorSize = 0;
let aliasSize = 0;
+ let targetRaw = '';
return start;
@@ -168,12 +182,12 @@ const tokenizeWikiLinkEmbed: Tokenizer = (effects, ok, nok) => {
if (code === null || code === -5 || code === -4 || code === -3) return nok(code);
if (code === CODE_LBRACKET) return nok(code);
if (code === CODE_RBRACKET) {
- if (targetSize === 0) return nok(code);
+ if (targetRaw.trim() === '') return nok(code);
effects.exit('wikiLinkTarget');
return close1(code);
}
if (code === CODE_HASH) {
- if (targetSize === 0) return nok(code);
+ if (targetRaw.trim() === '') return nok(code);
effects.exit('wikiLinkTarget');
effects.enter('wikiLinkSeparator');
effects.consume(code);
@@ -182,7 +196,7 @@ const tokenizeWikiLinkEmbed: Tokenizer = (effects, ok, nok) => {
return anchor as State;
}
if (code === CODE_PIPE) {
- if (targetSize === 0) return nok(code);
+ if (separatorEscapeLeavesEmpty(targetRaw)) return nok(code);
effects.exit('wikiLinkTarget');
effects.enter('wikiLinkSeparator');
effects.consume(code);
@@ -191,7 +205,7 @@ const tokenizeWikiLinkEmbed: Tokenizer = (effects, ok, nok) => {
return alias as State;
}
effects.consume(code);
- targetSize++;
+ targetRaw += characterForCode(code);
return target as State;
}
@@ -312,12 +326,37 @@ function exitAlias(this: CompileContext, token: Token) {
const raw = this.sliceSerialize(token);
const trimmed = raw.trim();
node.data.alias = trimmed.length ? trimmed : null;
- if (node.data.alias !== null && raw !== trimmed) {
+ if (raw !== trimmed) {
node.data.sourceAlias = raw;
}
}
+function normalizeSeparatorEscapes(node: WikiLinkMdast | WikiLinkEmbedMdast): void {
+ const before = {
+ target: node.data.target,
+ anchor: node.data.anchor ?? null,
+ alias: node.data.alias ?? null,
+ };
+ const after = normalizeWikiSeparatorEscapes(before, {
+ separatorCrossed: before.alias !== null || node.data.sourceAlias != null,
+ });
+
+ if (after.target !== before.target) {
+ node.data.sourceTarget ??= before.target;
+ node.data.target = after.target;
+ }
+ if (after.anchor !== before.anchor) {
+ node.data.sourceAnchor ??= before.anchor;
+ node.data.anchor = after.anchor;
+ }
+ if (after.alias !== before.alias) {
+ node.data.sourceAlias ??= before.alias;
+ node.data.alias = after.alias;
+ }
+}
+
function finalizeLabel(node: WikiLinkMdast | WikiLinkEmbedMdast): void {
+ normalizeSeparatorEscapes(node);
const { target, anchor, alias } = node.data;
const label = alias ? alias : anchor ? `${target}#${anchor}` : target;
node.value = label;
@@ -348,31 +387,35 @@ export const wikiLinkFromMarkdown: FromMarkdownExtension = {
},
};
-function rawSegmentOr(raw: string | null | undefined, current: string): string {
- return typeof raw === 'string' && raw.trim() === current ? raw : current;
+function wikiLinkToMarkdownHandler(opener: string): ToMarkdownHandle {
+ return (node: WikiLinkMdast | WikiLinkEmbedMdast, _parent, state, _info) => {
+ const data = node.data;
+ const inTableCell = state.stack.includes('tableCell');
+ const safe = (bytes: string): string => (inTableCell ? escapeTableCellPipes(bytes) : bytes);
+ const target = data?.target ?? '';
+ const anchor = data?.anchor;
+ const alias = data?.alias;
+ let out = `${opener}${safe(rawSegmentOr(data?.sourceTarget, target, 'separatorAdjacent'))}`;
+ if (anchor) {
+ out += `#${safe(rawSegmentOr(data?.sourceAnchor, anchor, 'separatorAdjacent'))}`;
+ } else {
+ const emptyAnchorRaw = safe(rawSegmentOr(data?.sourceAnchor, '', 'separatorAdjacent'));
+ if (emptyAnchorRaw.length > 0) out += `#${emptyAnchorRaw}`;
+ }
+ const aliasSegment = alias
+ ? rawSegmentOr(data?.sourceAlias, alias, 'alias')
+ : rawSegmentOr(data?.sourceAlias, '', 'alias');
+ if (aliasSegment.length > 0) {
+ const separator = inTableCell && !out.endsWith('\\') ? '\\|' : '|';
+ out += `${separator}${safe(aliasSegment)}`;
+ }
+ return `${out}]]`;
+ };
}
-const wikiLinkHandler: ToMarkdownHandle = (node) => {
- const wiki = node as unknown as WikiLinkMdast;
- const target = wiki.data?.target ?? '';
- const anchor = wiki.data?.anchor;
- const alias = wiki.data?.alias;
- let out = `[[${rawSegmentOr(wiki.data?.sourceTarget, target)}`;
- if (anchor) out += `#${rawSegmentOr(wiki.data?.sourceAnchor, anchor)}`;
- if (alias) out += `|${rawSegmentOr(wiki.data?.sourceAlias, alias)}`;
- return `${out}]]`;
-};
+const wikiLinkHandler: ToMarkdownHandle = wikiLinkToMarkdownHandler('[[');
-const wikiLinkEmbedHandler: ToMarkdownHandle = (node) => {
- const embed = node as unknown as WikiLinkEmbedMdast;
- const target = embed.data?.target ?? '';
- const anchor = embed.data?.anchor;
- const alias = embed.data?.alias;
- let out = `![[${target}`;
- if (anchor) out += `#${anchor}`;
- if (alias) out += `|${alias}`;
- return `${out}]]`;
-};
+const wikiLinkEmbedHandler: ToMarkdownHandle = wikiLinkToMarkdownHandler('![[');
export const wikiLinkToMarkdown: {
handlers: Record<string, ToMarkdownHandle>;
diff --git a/packages/core/src/registry/built-ins.ts b/packages/core/src/registry/built-ins.ts
index 6d921815b..9eb3fd381 100644
--- a/packages/core/src/registry/built-ins.ts
+++ b/packages/core/src/registry/built-ins.ts
@@ -695,16 +695,26 @@ function escapeHtmlText(value: string): string {
function serializeWikiEmbed(node: { attrs: { props?: unknown } }): MdastNodes {
const p = node.attrs.props as
- | { target?: string; alias?: string | null; anchor?: string | null }
+ | {
+ target?: string;
+ alias?: string | null;
+ anchor?: string | null;
+ sourceTarget?: string | null;
+ sourceAnchor?: string | null;
+ sourceAlias?: string | null;
+ }
| undefined;
const target = p?.target ?? '';
const alias = typeof p?.alias === 'string' && p.alias.length > 0 ? p.alias : null;
const anchor = typeof p?.anchor === 'string' && p.anchor.length > 0 ? p.anchor : null;
+ const sourceTarget = typeof p?.sourceTarget === 'string' ? p.sourceTarget : null;
+ const sourceAnchor = typeof p?.sourceAnchor === 'string' ? p.sourceAnchor : null;
+ const sourceAlias = typeof p?.sourceAlias === 'string' ? p.sourceAlias : null;
const label = alias ?? (anchor ? `${target}#${anchor}` : target);
return {
type: 'wikiLinkEmbed' as const,
value: label,
- data: { target, anchor, alias },
+ data: { target, anchor, alias, sourceTarget, sourceAnchor, sourceAlias },
children: [{ type: 'text' as const, value: label }],
} as unknown as MdastNodes;
}
diff --git a/packages/core/src/schema-snapshot.json b/packages/core/src/schema-snapshot.json
index 0da70a84d..db569d599 100644
--- a/packages/core/src/schema-snapshot.json
+++ b/packages/core/src/schema-snapshot.json
@@ -622,6 +622,15 @@
},
"sourceTitleMarker": {
"hasDefault": true
+ },
+ "sourceTarget": {
+ "hasDefault": true
+ },
+ "sourceAnchor": {
+ "hasDefault": true
+ },
+ "sourceAlias": {
+ "hasDefault": true
}
},
"excludes": "link",
diff --git a/packages/server/src/link-syntax.test.ts b/packages/server/src/link-syntax.test.ts
index 07c7847aa..81aa7486f 100644
--- a/packages/server/src/link-syntax.test.ts
+++ b/packages/server/src/link-syntax.test.ts
@@ -419,3 +419,117 @@ describe('cross-consumer divergence ledger', () => {
expect(readMarkdownLinkAt('[doc](./t.md "ti)tle")', 0)).toMatchObject({ href: './t.md' });
});
});
+
+describe('escaped alias separator', () => {
+ const ANCHOR_ROW = String.raw`[[targets/existing-page#details\|Wiki alias to details]]`;
+ const EXTERNAL_ROW = String.raw`[[https://inkeep.com\|External wiki link]]`;
+
+ test('escaped separator after an anchor leaves the anchor clean', () => {
+ expect(readWikiLinkAt(ANCHOR_ROW, 0)).toMatchObject({
+ embed: false,
+ target: 'targets/existing-page',
+ anchor: 'details',
+ alias: 'Wiki alias to details',
+ });
+ });
+
+ test('escaped separator with no anchor leaves the target clean', () => {
+ expect(readWikiLinkAt(EXTERNAL_ROW, 0)).toMatchObject({
+ embed: false,
+ target: 'https://inkeep.com',
+ anchor: null,
+ alias: 'External wiki link',
+ });
+ });
+
+ test('embed form with an escaped separator leaves the target clean', () => {
+ expect(readWikiLinkAt(String.raw`![[Attachments/pic.png\|Alt text]]`, 0)).toMatchObject({
+ embed: true,
+ target: 'Attachments/pic.png',
+ anchor: null,
+ alias: 'Alt text',
+ });
+ expect(readWikiLinkAt(String.raw`![[file.pdf#page=3\|Page 3]]`, 0)).toMatchObject({
+ embed: true,
+ target: 'file.pdf',
+ anchor: 'page=3',
+ alias: 'Page 3',
+ });
+ });
+
+ test('scanning a whole table row resolves both escaped shapes clean', () => {
+ const row = `| a | ${ANCHOR_ROW} | ${EXTERNAL_ROW} |`;
+ expect(matchWikiLinks(row)).toEqual([
+ expect.objectContaining({
+ embed: false,
+ target: 'targets/existing-page',
+ anchor: 'details',
+ alias: 'Wiki alias to details',
+ }),
+ expect.objectContaining({
+ embed: false,
+ target: 'https://inkeep.com',
+ anchor: null,
+ alias: 'External wiki link',
+ }),
+ ]);
+ });
+
+ test('raw captures keep describing the authored bytes across an escaped separator', () => {
+ const line = `| x | ${ANCHOR_ROW} |`;
+ const match = matchWikiLinks(line)[0];
+ expect(line.slice(match.start, match.end)).toBe(ANCHOR_ROW);
+ expect(match.targetRaw).toBe('targets/existing-page');
+ expect(match.anchorRaw).toBe('details\\');
+ expect(match.aliasRaw).toBe('Wiki alias to details');
+ });
+
+ test('escaped pipes folded into the alias unescape', () => {
+ expect(
+ matchWikiLinks(String.raw`[[a\|b\|c]]`).map((m) => ({ target: m.target, alias: m.alias })),
+ ).toEqual([{ target: 'a', alias: 'b|c' }]);
+ });
+
+ test('an escaped separator after an anchor with an empty anchor drops the anchor', () => {
+ expect(readWikiLinkAt(String.raw`[[Page#\|Alias]]`, 0)).toMatchObject({
+ target: 'Page',
+ anchor: null,
+ alias: 'Alias',
+ });
+ });
+
+ test('a target that is only the separator escape rejects', () => {
+ expect(readWikiLinkAt(String.raw`[[\|alias]]`, 0)).toBeNull();
+ expect(readWikiLinkAt(String.raw`[[ \|alias]]`, 0)).toBeNull();
+ });
+
+ test('a backslash not at the separator boundary stays literal', () => {
+ expect(readWikiLinkAt(String.raw`[[a\b|Alias]]`, 0)).toMatchObject({
+ target: String.raw`a\b`,
+ alias: 'Alias',
+ });
+ });
+
+ test('a trailing backslash with no alias stays literal', () => {
+ expect(readWikiLinkAt(String.raw`[[a\]]`, 0)).toMatchObject({
+ target: 'a\\',
+ anchor: null,
+ alias: null,
+ });
+ });
+
+ test('unescaped separators keep matching as before', () => {
+ expect(
+ readWikiLinkAt('[[targets/existing-page#details|Wiki alias to details]]', 0),
+ ).toMatchObject({
+ target: 'targets/existing-page',
+ anchor: 'details',
+ alias: 'Wiki alias to details',
+ });
+ expect(readWikiLinkAt('[[https://inkeep.com|External wiki link]]', 0)).toMatchObject({
+ target: 'https://inkeep.com',
+ anchor: null,
+ alias: 'External wiki link',
+ });
+ });
+});
diff --git a/packages/server/src/link-syntax.ts b/packages/server/src/link-syntax.ts
index 9760ca186..72e06a3ff 100644
--- a/packages/server/src/link-syntax.ts
+++ b/packages/server/src/link-syntax.ts
@@ -4,6 +4,8 @@
* (precedent #56) exists to prevent.
*/
+import { normalizeWikiSeparatorEscapes } from '@inkeep/open-knowledge-core';
+
const WIKI_BODY_SOURCE = String.raw`\[\[([^\n#[\]|]+)(?:#([^\n[\]|]+))?(?:\|([^\n[\]]+))?\]\]`;
const DEST_AND_TITLE_SOURCE = String.raw`\((<[^>\n]+>|[^)\s\n]+)((?:\s+(?:"[^"\n]*"|'[^'\n]*'|\([^)\n]*\)))?)\)`;
@@ -46,17 +48,24 @@ export interface MarkdownLinkMatch {
function toWikiLinkMatch(match: RegExpExecArray, start: number): WikiLinkMatch | null {
const targetRaw = match[2] ?? '';
- const target = targetRaw.trim();
- if (!target) return null;
const anchorRaw = match[3] ?? null;
const aliasRaw = match[4] ?? null;
+ const { target, anchor, alias } = normalizeWikiSeparatorEscapes(
+ {
+ target: targetRaw.trim(),
+ anchor: anchorRaw?.trim() || null,
+ alias: aliasRaw?.trim() || null,
+ },
+ { separatorCrossed: aliasRaw !== null },
+ );
+ if (!target) return null;
return {
embed: match[1] === '!',
target,
targetRaw,
- anchor: anchorRaw?.trim() || null,
+ anchor,
anchorRaw,
- alias: aliasRaw?.trim() || null,
+ alias,
aliasRaw,
start,
end: start + match[0].length,
diff --git a/packages/server/src/managed-rename-rewrite.test.ts b/packages/server/src/managed-rename-rewrite.test.ts
index 1f5affc59..0a200a3b8 100644
--- a/packages/server/src/managed-rename-rewrite.test.ts
+++ b/packages/server/src/managed-rename-rewrite.test.ts
@@ -1,4 +1,9 @@
-import { resolveAssetProjectPath, resolveInternalHref } from '@inkeep/open-knowledge-core';
+import {
+ MarkdownManager,
+ resolveAssetProjectPath,
+ resolveInternalHref,
+ sharedExtensions,
+} from '@inkeep/open-knowledge-core';
import { describe, expect, test } from 'vitest';
import {
rewriteAssetReferencesForRename,
@@ -7,6 +12,7 @@ import {
rewriteOutboundMarkdownLinksForSourceMove,
rewriteWikiLinksForDocumentRename,
} from './managed-rename-rewrite.ts';
+import { findWikiLinkAttrs, type PmJson } from './wiki-pm-json.test-helper.ts';
describe('rewriteWikiLinksForDocumentRename', () => {
test('rewrites matching wiki-links while preserving alias and anchor', () => {
@@ -22,6 +28,15 @@ describe('rewriteWikiLinksForDocumentRename', () => {
});
});
+ test('preserves padded alias bytes on rename', () => {
+ expect(
+ rewriteWikiLinksForDocumentRename('See [[old| Install Guide ]] here.\n', 'old', 'new'),
+ ).toEqual({
+ markdown: 'See [[new| Install Guide ]] here.\n',
+ rewrites: 1,
+ });
+ });
+
test('preserves escaped wiki-link brackets', () => {
expect(rewriteWikiLinksForDocumentRename('See \\[[old]] here.\n', 'old', 'new')).toEqual({
markdown: 'See \\[[old]] here.\n',
@@ -959,3 +974,185 @@ describe('rewritten hrefs round-trip back through the canonical resolvers', () =
);
});
});
+
+describe('rewriteWikiLinksForDocumentRename — escaped alias separators inside GFM tables', () => {
+ const mdManager = new MarkdownManager({ extensions: sharedExtensions });
+
+ function dataRowCellCount(markdown: string): number {
+ let count = -1;
+ const walk = (node: PmJson): void => {
+ if (
+ node.type === 'tableRow' &&
+ (node.content ?? []).some((child) => child.type === 'tableCell')
+ ) {
+ count = (node.content ?? []).length;
+ }
+ for (const child of node.content ?? []) walk(child);
+ };
+ walk(mdManager.parse(markdown) as unknown as PmJson);
+ return count;
+ }
+
+ test('no-anchor rename keeps the escape and the cell whole', () => {
+ const row = '| Link |\n| --- |\n| [[Page\\|Friendly label]] |';
+ const result = rewriteWikiLinksForDocumentRename(row, 'Page', 'NewPage');
+ expect(result).toEqual({
+ markdown: '| Link |\n| --- |\n| [[NewPage\\|Friendly label]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount(result.markdown)).toBe(1);
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewPage',
+ alias: 'Friendly label',
+ });
+ });
+
+ test('anchor rename keeps the escape and the cell whole', () => {
+ const row = '| Link |\n| --- |\n| [[Page#sec\\|Alias]] |';
+ const result = rewriteWikiLinksForDocumentRename(row, 'Page', 'NewPage');
+ expect(result).toEqual({
+ markdown: '| Link |\n| --- |\n| [[NewPage#sec\\|Alias]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount(result.markdown)).toBe(1);
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewPage',
+ anchor: 'sec',
+ alias: 'Alias',
+ });
+ });
+
+ test('empty-anchor rename keeps the authored separator replay', () => {
+ const row = '| Link |\n| --- |\n| [[Page#\\|Alias]] |';
+ const result = rewriteWikiLinksForDocumentRename(row, 'Page', 'NewPage');
+ expect(result).toEqual({
+ markdown: '| Link |\n| --- |\n| [[NewPage#\\|Alias]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount(result.markdown)).toBe(1);
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewPage',
+ anchor: null,
+ alias: 'Alias',
+ });
+ });
+
+ test('folded-pipe alias rename keeps every escape and the cell whole', () => {
+ const row = '| Link |\n| --- |\n| [[a\\|b\\|c]] |';
+ const result = rewriteWikiLinksForDocumentRename(row, 'a', 'NewA');
+ expect(result).toEqual({
+ markdown: '| Link |\n| --- |\n| [[NewA\\|b\\|c]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount(result.markdown)).toBe(1);
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewA',
+ alias: 'b|c',
+ });
+ });
+
+ test('escape-then-whitespace target rename keeps the escape and the cell whole', () => {
+ const row = '| Link |\n| --- |\n| [[Page\\ |Alias]] |';
+ const result = rewriteWikiLinksForDocumentRename(row, 'Page', 'NewPage');
+ expect(result).toEqual({
+ markdown: '| Link |\n| --- |\n| [[NewPage\\|Alias]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount(result.markdown)).toBe(1);
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewPage',
+ alias: 'Alias',
+ });
+ });
+
+ test('whitespace-only anchor rename matches the serializer canonical form', () => {
+ const result = rewriteWikiLinksForDocumentRename(
+ 'See [[Page# |Alias]] here.\n',
+ 'Page',
+ 'NewPage',
+ );
+ expect(result).toEqual({
+ markdown: 'See [[NewPage|Alias]] here.\n',
+ rewrites: 1,
+ });
+ expect(mdManager.serialize(mdManager.parse(result.markdown)).trim()).toBe(
+ result.markdown.trim(),
+ );
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewPage',
+ anchor: null,
+ alias: 'Alias',
+ });
+ });
+
+ test('whitespace-only alias rename is a serializer fixed point', () => {
+ const row = '| Link |\n| --- |\n| [[Page\\| ]] |';
+ const result = rewriteWikiLinksForDocumentRename(row, 'Page', 'NewPage');
+ expect(result).toEqual({
+ markdown: '| Link |\n| --- |\n| [[NewPage\\| ]] |',
+ rewrites: 1,
+ });
+ expect(mdManager.serialize(mdManager.parse(result.markdown)).trim()).toBe(result.markdown);
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewPage',
+ alias: null,
+ });
+ });
+
+ test('whitespace-only alias behind an anchor rename is a serializer fixed point', () => {
+ const row = '| L |\n| --- |\n| [[Page#sec\\| ]] |';
+ const result = rewriteWikiLinksForDocumentRename(row, 'Page', 'NewPage');
+ expect(result).toEqual({
+ markdown: '| L |\n| --- |\n| [[NewPage#sec\\| ]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount(result.markdown)).toBe(1);
+ expect(mdManager.serialize(mdManager.parse(result.markdown)).trim()).toBe(result.markdown);
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewPage',
+ anchor: 'sec',
+ alias: null,
+ });
+ });
+
+ test('escaped-target rename with a whitespace anchor repairs the table cell', () => {
+ const row = '| Link |\n| --- |\n| [[Page\\# |Alias]] |';
+ const result = rewriteWikiLinksForDocumentRename(row, 'Page', 'NewPage');
+ expect(result).toEqual({
+ markdown: '| Link |\n| --- |\n| [[NewPage\\|Alias]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount(result.markdown)).toBe(1);
+ expect(mdManager.serialize(mdManager.parse(result.markdown)).trim()).toBe(result.markdown);
+ expect(findWikiLinkAttrs(mdManager.parse(result.markdown) as unknown as PmJson)).toMatchObject({
+ target: 'NewPage',
+ anchor: null,
+ alias: 'Alias',
+ });
+ });
+
+ test('an unescaped separator stays unescaped on rename', () => {
+ expect(
+ rewriteWikiLinksForDocumentRename('| Link |\n| --- |\n| [[Page|Alias]] |', 'Page', 'NewPage'),
+ ).toEqual({
+ markdown: '| Link |\n| --- |\n| [[NewPage|Alias]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount('| Link |\n| --- |\n| [[NewPage|Alias]] |')).toBe(2);
+ });
+
+ test('embed asset rename inside a table keeps the escape and the cell whole', () => {
+ const row = '| pic |\n| --- |\n| ![[Attach/pic.png\\|alt]] |';
+ const result = rewriteAssetReferencesForRename(
+ row,
+ 'doc.md',
+ 'Attach/pic.png',
+ 'Attach/new.png',
+ );
+ expect(result).toEqual({
+ markdown: '| pic |\n| --- |\n| ![[Attach/new.png\\|alt]] |',
+ rewrites: 1,
+ });
+ expect(dataRowCellCount(result.markdown)).toBe(1);
+ });
+});
diff --git a/packages/server/src/managed-rename-rewrite.ts b/packages/server/src/managed-rename-rewrite.ts
index 627394692..f4c88cb1b 100644
--- a/packages/server/src/managed-rename-rewrite.ts
+++ b/packages/server/src/managed-rename-rewrite.ts
@@ -4,6 +4,7 @@ import {
encodeHrefPathSegment,
isExternalHref,
type JsxSrcRefTagSpec,
+ rawSegmentOr,
resolveAssetProjectPath,
resolveInternalHref,
} from '@inkeep/open-knowledge-core';
@@ -12,7 +13,7 @@ import {
readJsxSrcRefTagAt,
resolveJsxSrcRefTarget,
} from './jsx-src-ref-tags.ts';
-import { readMarkdownLinkAt, readWikiLinkAt } from './link-syntax.ts';
+import { readMarkdownLinkAt, readWikiLinkAt, type WikiLinkMatch } from './link-syntax.ts';
interface FenceState {
char: '`' | '~';
@@ -68,21 +69,35 @@ function readInlineCode(line: string, start: number): { nextIndex: number } | nu
function readWikiLink(
line: string,
start: number,
-): { target: string; alias: string | null; anchor: string | null; nextIndex: number } | null {
+): {
+ target: string;
+ targetRaw: string;
+ alias: string | null;
+ aliasRaw: string | null;
+ anchor: string | null;
+ anchorRaw: string | null;
+ nextIndex: number;
+} | null {
const match = readWikiLinkAt(line, start);
if (!match) return null;
return {
target: match.target,
+ targetRaw: match.targetRaw,
alias: match.alias,
+ aliasRaw: match.aliasRaw,
anchor: match.anchor,
+ anchorRaw: match.anchorRaw,
nextIndex: match.end,
};
}
interface WikiLinkOrEmbed {
target: string;
+ targetRaw: string;
alias: string | null;
+ aliasRaw: string | null;
anchor: string | null;
+ anchorRaw: string | null;
nextIndex: number;
embed: boolean;
}
@@ -92,8 +107,11 @@ function readWikiLinkOrEmbed(line: string, start: number): WikiLinkOrEmbed | nul
if (!match) return null;
return {
target: match.target,
+ targetRaw: match.targetRaw,
alias: match.alias,
+ aliasRaw: match.aliasRaw,
anchor: match.anchor,
+ anchorRaw: match.anchorRaw,
nextIndex: match.end,
embed: match.embed,
};
@@ -155,6 +173,31 @@ function splitLines(markdown: string): Array<{ line: string; ending: string }> {
return lines;
}
+type WikiLinkRenameSegments = Pick<
+ WikiLinkMatch,
+ 'targetRaw' | 'anchor' | 'anchorRaw' | 'alias' | 'aliasRaw'
+>;
+
+function renderWikiLinkSegments(segments: WikiLinkRenameSegments, nextTarget: string): string {
+ let out = `[[${nextTarget}`;
+ const anchorRaw = segments.anchorRaw;
+ const anchorSegmentSurvived = anchorRaw !== null && anchorRaw.trim() !== '';
+ if (segments.anchor) {
+ out += `#${rawSegmentOr(anchorRaw, segments.anchor, 'separatorAdjacent')}`;
+ } else if (anchorSegmentSurvived) {
+ const emptyAnchorRaw = rawSegmentOr(anchorRaw, '', 'separatorAdjacent');
+ if (emptyAnchorRaw.length > 0) out += `#${emptyAnchorRaw}`;
+ }
+ const alias = segments.alias
+ ? rawSegmentOr(segments.aliasRaw, segments.alias, 'alias')
+ : rawSegmentOr(segments.aliasRaw, '', 'alias');
+ if (alias.length > 0) {
+ if (!anchorSegmentSurvived && segments.targetRaw.trim().endsWith('\\')) out += '\\';
+ out += `|${alias}`;
+ }
+ return `${out}]]`;
+}
+
function rewriteWikiLinksInLine(
line: string,
oldDocName: string,
@@ -190,7 +233,7 @@ function rewriteWikiLinksInLine(
const wikiLink = readWikiLink(line, idx);
if (wikiLink) {
if (wikiLink.target === oldDocName) {
- rewritten += `[[${newDocName}${wikiLink.anchor ? `#${wikiLink.anchor}` : ''}${wikiLink.alias ? `|${wikiLink.alias}` : ''}]]`;
+ rewritten += renderWikiLinkSegments(wikiLink, newDocName);
rewrites++;
} else {
rewritten += line.slice(idx, wikiLink.nextIndex);
@@ -420,7 +463,7 @@ function rewriteMarkdownLinksInLine(
}
function renderWikiLinkOrEmbed(link: WikiLinkOrEmbed, target: string): string {
- return `${link.embed ? '!' : ''}[[${target}${link.anchor ? `#${link.anchor}` : ''}${link.alias ? `|${link.alias}` : ''}]]`;
+ return `${link.embed ? '!' : ''}${renderWikiLinkSegments(link, target)}`;
}
const HTML_ASSET_ATTR_RE =
diff --git a/packages/server/src/wiki-grammar-parity.test.ts b/packages/server/src/wiki-grammar-parity.test.ts
new file mode 100644
index 000000000..c1cf7596a
--- /dev/null
+++ b/packages/server/src/wiki-grammar-parity.test.ts
@@ -0,0 +1,283 @@
+import {
+ type CleanWikiSegments,
+ MarkdownManager,
+ parseWikiLink,
+ sharedExtensions,
+} from '@inkeep/open-knowledge-core';
+import { describe, expect, test } from 'vitest';
+import { readWikiLinkAt } from './link-syntax.ts';
+import {
+ findWikiEmbedMarkAttrs,
+ findWikiLinkAttrs,
+ type PmJson,
+} from './wiki-pm-json.test-helper.ts';
+
+let manager: MarkdownManager | null = null;
+function markdownManager(): MarkdownManager {
+ manager ??= new MarkdownManager({ extensions: sharedExtensions });
+ return manager;
+}
+
+function segmentsFrom(attrs: Record<string, unknown> | null): CleanWikiSegments | null {
+ if (!attrs) return null;
+ return {
+ target: String(attrs.target ?? ''),
+ anchor: (attrs.anchor as string | null) ?? null,
+ alias: (attrs.alias as string | null) ?? null,
+ };
+}
+
+function viaServerScanner(source: string): CleanWikiSegments | null {
+ const match = readWikiLinkAt(source, 0);
+ return match ? { target: match.target, anchor: match.anchor, alias: match.alias } : null;
+}
+
+function viaCoreRegex(source: string): CleanWikiSegments | null {
+ const parsed = parseWikiLink(source);
+ return parsed ? { target: parsed.target, anchor: parsed.anchor, alias: parsed.alias } : null;
+}
+
+function viaMicromark(source: string): CleanWikiSegments | null {
+ return segmentsFrom(findWikiLinkAttrs(markdownManager().parse(source) as PmJson));
+}
+
+function viaServerScannerEmbed(source: string): CleanWikiSegments | null {
+ const match = readWikiLinkAt(source, 0);
+ return match?.embed ? { target: match.target, anchor: match.anchor, alias: match.alias } : null;
+}
+
+function viaCoreRegexEmbed(source: string): CleanWikiSegments | null {
+ return viaCoreRegex(source.slice(1));
+}
+
+function viaMicromarkEmbed(source: string): CleanWikiSegments | null {
+ return segmentsFrom(findWikiEmbedMarkAttrs(markdownManager().parse(source) as PmJson));
+}
+
+const FIXTURES: Array<{
+ name: string;
+ source: string;
+ form?: 'embed';
+ expected: CleanWikiSegments | null;
+}> = [
+ {
+ name: 'bare target',
+ source: '[[Page]]',
+ expected: { target: 'Page', anchor: null, alias: null },
+ },
+ {
+ name: 'anchor only',
+ source: '[[Page#Heading]]',
+ expected: { target: 'Page', anchor: 'Heading', alias: null },
+ },
+ {
+ name: 'alias only',
+ source: '[[Page|Alias]]',
+ expected: { target: 'Page', anchor: null, alias: 'Alias' },
+ },
+ {
+ name: 'anchor and alias',
+ source: '[[Page#Heading|Alias]]',
+ expected: { target: 'Page', anchor: 'Heading', alias: 'Alias' },
+ },
+ {
+ name: 'escaped separator after an anchor',
+ source: String.raw`[[targets/existing-page#details\|Wiki alias to details]]`,
+ expected: {
+ target: 'targets/existing-page',
+ anchor: 'details',
+ alias: 'Wiki alias to details',
+ },
+ },
+ {
+ name: 'escaped separator with no anchor',
+ source: String.raw`[[https://inkeep.com\|External wiki link]]`,
+ expected: { target: 'https://inkeep.com', anchor: null, alias: 'External wiki link' },
+ },
+ {
+ name: 'escaped separators folded into the alias',
+ source: String.raw`[[a\|b\|c]]`,
+ expected: { target: 'a', anchor: null, alias: 'b|c' },
+ },
+ {
+ name: 'escaped separator after an anchor with an empty anchor',
+ source: String.raw`[[Page#\|Alias]]`,
+ expected: { target: 'Page', anchor: null, alias: 'Alias' },
+ },
+ {
+ name: 'a target that is only the separator escape',
+ source: String.raw`[[\|alias]]`,
+ expected: null,
+ },
+ {
+ name: 'a whitespace-prefixed target that is only the separator escape',
+ source: String.raw`[[ \|alias]]`,
+ expected: null,
+ },
+ {
+ name: 'unescaped later pipes fold into the alias',
+ source: '[[a|b|c]]',
+ expected: { target: 'a', anchor: null, alias: 'b|c' },
+ },
+ {
+ name: 'a backslash not at the separator boundary stays literal',
+ source: String.raw`[[a\b|Alias]]`,
+ expected: { target: String.raw`a\b`, anchor: null, alias: 'Alias' },
+ },
+ {
+ name: 'authored padding is trimmed out of the resolved values',
+ source: '[[ Page # Heading | Alias ]]',
+ expected: { target: 'Page', anchor: 'Heading', alias: 'Alias' },
+ },
+ {
+ name: 'anchor may contain further hashes',
+ source: '[[a#b#c]]',
+ expected: { target: 'a', anchor: 'b#c', alias: null },
+ },
+ {
+ name: 'an all-whitespace target with an alias',
+ source: '[[ |alias]]',
+ expected: null,
+ },
+ {
+ name: 'an all-whitespace target without a separator',
+ source: '[[ ]]',
+ expected: null,
+ },
+ {
+ name: 'a target that is only a tab with an alias',
+ source: '[[\t|alias]]',
+ expected: null,
+ },
+ {
+ name: 'a target that is only a tab without a separator',
+ source: '[[\t]]',
+ expected: null,
+ },
+ {
+ name: 'an escape-then-whitespace target with an alias',
+ source: String.raw`[[\ |alias]]`,
+ expected: null,
+ },
+ {
+ name: 'a whitespace-padded escape-then-whitespace target with an alias',
+ source: String.raw`[[ \ |alias]]`,
+ expected: null,
+ },
+ {
+ name: 'a whitespace-only alias after an escaped separator',
+ source: String.raw`[[Page\| ]]`,
+ expected: { target: 'Page', anchor: null, alias: null },
+ },
+ {
+ name: 'a whitespace-only alias after an escaped separator behind an anchor',
+ source: String.raw`[[Page#head\| ]]`,
+ expected: { target: 'Page', anchor: 'head', alias: null },
+ },
+ {
+ name: 'a whitespace-only anchor drops on all paths',
+ source: '[[Page# |Alias]]',
+ expected: { target: 'Page', anchor: null, alias: 'Alias' },
+ },
+ {
+ name: 'a whitespace-only target before a hash anchor',
+ source: '[[ #Heading]]',
+ expected: null,
+ },
+ {
+ name: 'a whitespace-only target with an anchor and an alias',
+ source: '[[ #a|b]]',
+ expected: null,
+ },
+ {
+ name: 'an escape-backslash target before a hash anchor stays a link',
+ source: String.raw`[[ \#Heading]]`,
+ expected: { target: '\\', anchor: 'Heading', alias: null },
+ },
+ {
+ name: 'embed form of the escaped separator with no anchor',
+ source: String.raw`![[Page\|Alias]]`,
+ form: 'embed',
+ expected: { target: 'Page', anchor: null, alias: 'Alias' },
+ },
+ {
+ name: 'embed form of the escaped separator after an anchor',
+ source: String.raw`![[Page#sec\|Alias]]`,
+ form: 'embed',
+ expected: { target: 'Page', anchor: 'sec', alias: 'Alias' },
+ },
+ {
+ name: 'embed form of the escaped empty-anchor separator',
+ source: String.raw`![[Page#\|Alias]]`,
+ form: 'embed',
+ expected: { target: 'Page', anchor: null, alias: 'Alias' },
+ },
+ {
+ name: 'embed form of escaped separators folded into the alias',
+ source: String.raw`![[a\|b\|c]]`,
+ form: 'embed',
+ expected: { target: 'a', anchor: null, alias: 'b|c' },
+ },
+ {
+ name: 'embed form of a target that is only the separator escape',
+ source: String.raw`![[\|alias]]`,
+ form: 'embed',
+ expected: null,
+ },
+ {
+ name: 'embed form of an all-whitespace target with an alias',
+ source: '![[ |alias]]',
+ form: 'embed',
+ expected: null,
+ },
+ {
+ name: 'embed form of a target that is only a tab with an alias',
+ source: '![[\t|alias]]',
+ form: 'embed',
+ expected: null,
+ },
+ {
+ name: 'embed form of an escape-then-whitespace target with an alias',
+ source: String.raw`![[\ |alias]]`,
+ form: 'embed',
+ expected: null,
+ },
+ {
+ name: 'embed form of a whitespace-only anchor drops on all paths',
+ source: '![[Page# |Alias]]',
+ form: 'embed',
+ expected: { target: 'Page', anchor: null, alias: 'Alias' },
+ },
+ {
+ name: 'a whitespace-only anchor with no alias drops on all paths',
+ source: '[[Page# ]]',
+ expected: { target: 'Page', anchor: null, alias: null },
+ },
+];
+
+describe('wiki grammar parity across the three sibling implementations (the core-regex embed leg reuses the link-leg adapter on the !-stripped source; the scanner and micromark embed legs parse the embed form natively)', () => {
+ const LEGS = {
+ link: [viaServerScanner, viaCoreRegex, viaMicromark] as const,
+ embed: [viaServerScannerEmbed, viaCoreRegexEmbed, viaMicromarkEmbed] as const,
+ };
+ const LEG_TITLES = ['server line scanner', 'core parseWikiLink', 'core micromark parse path'];
+
+ for (const { name, source, form, expected } of FIXTURES) {
+ LEGS[form === 'embed' ? 'embed' : 'link'].forEach((via, legIndex) => {
+ test(`${name} — ${LEG_TITLES[legIndex]}${form === 'embed' ? ' (embed)' : ''}`, () => {
+ expect(via(source)).toEqual(expected);
+ });
+ });
+ }
+
+ test('the three agree with each other, not merely with the fixture table', () => {
+ for (const { source, form } of FIXTURES) {
+ const [viaServer, viaCore, viaMicro] = LEGS[form === 'embed' ? 'embed' : 'link'];
+ const server = viaServer(source);
+ const coreRegex = viaCore(source);
+ const micromark = viaMicro(source);
+ expect({ source, coreRegex }).toEqual({ source, coreRegex: server });
+ expect({ source, micromark }).toEqual({ source, micromark: server });
+ }
+ });
+});
diff --git a/packages/server/src/wiki-pm-json.test-helper.ts b/packages/server/src/wiki-pm-json.test-helper.ts
new file mode 100644
index 000000000..42f41673c
--- /dev/null
+++ b/packages/server/src/wiki-pm-json.test-helper.ts
@@ -0,0 +1,29 @@
+export type PmJson = {
+ type?: string;
+ attrs?: Record<string, unknown>;
+ marks?: PmJson[];
+ text?: string;
+ content?: PmJson[];
+};
+
+export function findWikiLinkAttrs(node: PmJson): Record<string, unknown> | null {
+ if (node.type === 'wikiLink') return node.attrs ?? null;
+ for (const child of node.content ?? []) {
+ const found = findWikiLinkAttrs(child);
+ if (found) return found;
+ }
+ return null;
+}
+
+export function findWikiEmbedMarkAttrs(node: PmJson): Record<string, unknown> | null {
+ for (const mark of node.marks ?? []) {
+ if (mark.type === 'link' && mark.attrs?.sourceForm === 'wikiembed') {
+ return mark.attrs as Record<string, unknown>;
+ }
+ }
+ for (const child of node.content ?? []) {
+ const found = findWikiEmbedMarkAttrs(child);
+ if (found) return found;
+ }
+ return null;
+}