Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

feat(open-knowledge): bias @mention autocomplete toward page context (#2116)

Andrew Mikofalvya75181977f8e
diff --git a/.changeset/wiki-link-mention-ranking.md b/.changeset/wiki-link-mention-ranking.md
new file mode 100644
index 000000000..a4f37ae8e
--- /dev/null
+++ b/.changeset/wiki-link-mention-ranking.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge-app": patch
+---
+
+Improve `[[` wiki-link ("@mention") autocomplete ranking to surface the most relevant link targets first. The page you're editing and its link-graph neighbors (incoming and outgoing links) are now boosted, so opening the picker leads with the pages you're most likely to link to; docs under skill/tooling folders (`.agents`, `.claude`, `.cursor`) are deprioritized as knowledge-base noise (deprioritized, not hidden — a skill still appears when it's the best match). Both the WYSIWYG and the source-mode `[[` pickers re-rank in lockstep. Ranking for the command palette, full-text, and MCP search is unchanged.
diff --git a/packages/app/src/editor/SourceEditor.tsx b/packages/app/src/editor/SourceEditor.tsx
index 4d9a548ce..e732ff1f6 100644
--- a/packages/app/src/editor/SourceEditor.tsx
+++ b/packages/app/src/editor/SourceEditor.tsx
@@ -153,6 +153,7 @@ export function SourceEditor({
ydoc: provider.document,
wordWrapCompartment,
wordWrap,
+ currentDocName: resolvedDocName,
}),
createSourcePolishExtension(),
sourceClipboard,
diff --git a/packages/app/src/editor/extensions/nested-cm-extensions.ts b/packages/app/src/editor/extensions/nested-cm-extensions.ts
index 9f1763549..57cc8f584 100644
--- a/packages/app/src/editor/extensions/nested-cm-extensions.ts
+++ b/packages/app/src/editor/extensions/nested-cm-extensions.ts
@@ -93,6 +93,7 @@ interface NestedCMOptions {
wordWrapCompartment?: Compartment;
wordWrap?: boolean;
extraKeymaps?: Extension;
+ currentDocName?: string | null;
}
export function createNestedCMExtensions(options: NestedCMOptions): Extension[] {
@@ -102,7 +103,7 @@ export function createNestedCMExtensions(options: NestedCMOptions): Extension[]
return [
markdown({ base: markdownLanguage, extensions: [GFM], codeLanguages }),
- createWikiLinkSourceExtension(),
+ createWikiLinkSourceExtension(options.currentDocName ?? null),
createMdLinkSourceExtension(),
...(ydoc ? [createAgentFlashSourceExtension(ydoc)] : []),
keymap.of([]),
diff --git a/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts b/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts
index 2872ffdad..cdba3b948 100644
--- a/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts
+++ b/packages/app/src/editor/extensions/wiki-link-suggestion.test.ts
@@ -1,12 +1,17 @@
import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test';
import type { HeadingEntry } from '@inkeep/open-knowledge-core';
import {
+ autocompleteBoost,
buildAnchorItems,
buildSuggestionItems,
computeFallbackAttrs,
fetchPages,
+ filterPages,
+ isSkillFolderDoc,
+ loadWikiLinkContext,
type PageItem,
parseQuery,
+ type WikiLinkContext,
wikiLinkMatcher,
} from './wiki-link-suggestion';
@@ -369,3 +374,223 @@ describe('fetchPages', () => {
expect(result.some((item) => item.kind === 'folder')).toBe(false);
});
});
+
+describe('isSkillFolderDoc', () => {
+ test('matches docs under .agents / .claude / .cursor at any depth', () => {
+ expect(isSkillFolderDoc('.claude/skills/foo/SKILL')).toBe(true);
+ expect(isSkillFolderDoc('.agents/rules/bar')).toBe(true);
+ expect(isSkillFolderDoc('.cursor/rules/baz')).toBe(true);
+ expect(isSkillFolderDoc('public/open-knowledge/.claude/skills/x')).toBe(true);
+ });
+
+ test('does not match ordinary docs or look-alike folder names', () => {
+ expect(isSkillFolderDoc('guides/getting-started')).toBe(false);
+ expect(isSkillFolderDoc('claude/notes')).toBe(false); // no leading dot
+ expect(isSkillFolderDoc('agents-overview')).toBe(false);
+ });
+});
+
+describe('autocompleteBoost', () => {
+ const ctx = (over: Partial<WikiLinkContext> = {}): WikiLinkContext => ({
+ currentDocName: null,
+ connectedDocNames: new Set(),
+ ...over,
+ });
+
+ test('penalizes skill-folder docs', () => {
+ expect(autocompleteBoost('.claude/skills/foo/SKILL', ctx())).toBe(-200);
+ });
+
+ test('boosts the current page and link-graph neighbors, neighbor > current', () => {
+ expect(autocompleteBoost('current', ctx({ currentDocName: 'current' }))).toBe(50);
+ expect(autocompleteBoost('neighbor', ctx({ connectedDocNames: new Set(['neighbor']) }))).toBe(
+ 100,
+ );
+ });
+
+ test('combines penalty and link boost additively (a linked skill is still demoted)', () => {
+ const linkedSkill = autocompleteBoost(
+ '.claude/skills/foo/SKILL',
+ ctx({ connectedDocNames: new Set(['.claude/skills/foo/SKILL']) }),
+ );
+ expect(linkedSkill).toBe(-100);
+ });
+
+ test('returns 0 for an ordinary doc with empty context', () => {
+ expect(autocompleteBoost('guides/intro', ctx())).toBe(0);
+ });
+});
+
+describe('context-aware ranking', () => {
+ test('empty query: neighbors and current page float up, skills sink', () => {
+ const corpus: PageItem[] = [
+ { docName: 'alpha', title: 'Alpha' },
+ { docName: '.claude/skills/foo/SKILL', title: 'Foo' },
+ { docName: 'beta', title: 'Beta' },
+ { docName: 'gamma', title: 'Gamma' },
+ ];
+ const context: WikiLinkContext = {
+ currentDocName: 'beta',
+ connectedDocNames: new Set(['gamma']),
+ };
+ expect(filterPages(corpus, '', context).map((p) => p.docName)).toEqual([
+ 'gamma', // linked neighbor (+100)
+ 'beta', // current page (+50)
+ 'alpha', // ordinary (0)
+ '.claude/skills/foo/SKILL', // skill (-200)
+ ]);
+ });
+
+ test('empty query without context preserves source order (byte-identical to slice)', () => {
+ const corpus: PageItem[] = [
+ { docName: 'alpha', title: 'Alpha' },
+ { docName: 'beta', title: 'Beta' },
+ { docName: 'gamma', title: 'Gamma' },
+ ];
+ expect(filterPages(corpus, '').map((p) => p.docName)).toEqual(['alpha', 'beta', 'gamma']);
+ });
+
+ test('typed query: a skill is deprioritized below a stronger non-skill match but still listed', () => {
+ const corpus: PageItem[] = [
+ { docName: '.claude/skills/notes/SKILL', title: 'Project notes overview' },
+ { docName: 'notes', title: 'Notes' },
+ ];
+ expect(filterPages(corpus, 'notes').map((p) => p.docName)).toEqual([
+ 'notes',
+ '.claude/skills/notes/SKILL',
+ ]);
+ });
+
+ test('typed query: a linked neighbor outranks an equal-tier non-linked match', () => {
+ const corpus: PageItem[] = [
+ { docName: 'guide-alpha', title: 'Guide alpha' },
+ { docName: 'guide-beta', title: 'Guide beta' },
+ ];
+ const context: WikiLinkContext = {
+ currentDocName: 'somewhere-else',
+ connectedDocNames: new Set(['guide-beta']),
+ };
+ expect(filterPages(corpus, 'guide', context).map((p) => p.docName)).toEqual([
+ 'guide-beta',
+ 'guide-alpha',
+ ]);
+ });
+
+ test('typed query: a boosted neighbor ranked outside the natural top-8 still surfaces', () => {
+ const corpus: PageItem[] = Array.from({ length: 9 }, (_, i) => ({
+ docName: `item-${i + 1}`,
+ title: `Item ${i + 1}`,
+ }));
+ const noContext = filterPages(corpus, 'item').map((p) => p.docName);
+ expect(noContext).toHaveLength(8);
+ expect(noContext).not.toContain('item-9');
+
+ const withNeighbor = filterPages(corpus, 'item', {
+ currentDocName: 'elsewhere',
+ connectedDocNames: new Set(['item-9']),
+ }).map((p) => p.docName);
+ expect(withNeighbor).toContain('item-9');
+ });
+});
+
+describe('loadWikiLinkContext', () => {
+ const realFetch = globalThis.fetch;
+
+ function stubLinks(routes: {
+ forward?: { status?: number; body: unknown };
+ back?: { status?: number; body: unknown };
+ }) {
+ globalThis.fetch = mock(async (input: RequestInfo | URL) => {
+ const url = typeof input === 'string' ? input : input.toString();
+ const route = url.startsWith('/api/forward-links')
+ ? routes.forward
+ : url.startsWith('/api/backlinks')
+ ? routes.back
+ : undefined;
+ const status = route?.status ?? (route ? 200 : 404);
+ return new Response(JSON.stringify(route?.body ?? {}), {
+ status,
+ headers: { 'content-type': 'application/json' },
+ });
+ }) as typeof globalThis.fetch;
+ }
+
+ afterEach(() => {
+ globalThis.fetch = realFetch;
+ });
+
+ test('returns an empty context for a null docName without fetching', async () => {
+ let called = false;
+ globalThis.fetch = mock(async () => {
+ called = true;
+ return new Response('{}', { status: 200 });
+ }) as typeof globalThis.fetch;
+ const ctx = await loadWikiLinkContext(null);
+ expect(ctx).toEqual({ currentDocName: null, connectedDocNames: new Set() });
+ expect(called).toBe(false);
+ });
+
+ test('merges outgoing doc links with incoming sources and excludes external links', async () => {
+ stubLinks({
+ forward: {
+ body: {
+ docName: 'me',
+ forwardLinks: [
+ { kind: 'doc', docName: 'out-a', anchor: null, title: 'A', snippet: null },
+ { kind: 'external', url: 'https://example.com', title: 'x', snippet: null },
+ ],
+ },
+ },
+ back: {
+ body: {
+ docName: 'me',
+ backlinks: [{ source: 'in-b', anchor: null, title: 'B', snippet: null }],
+ },
+ },
+ });
+ const ctx = await loadWikiLinkContext('me');
+ expect(ctx.currentDocName).toBe('me');
+ expect([...ctx.connectedDocNames].sort()).toEqual(['in-b', 'out-a']);
+ });
+
+ test('drops a self-link so the current page earns the current-page boost, not the neighbor boost', async () => {
+ stubLinks({
+ forward: {
+ body: {
+ docName: 'me',
+ forwardLinks: [
+ { kind: 'doc', docName: 'me', anchor: null, title: 'self', snippet: null },
+ { kind: 'doc', docName: 'friend', anchor: null, title: 'F', snippet: null },
+ ],
+ },
+ },
+ back: { body: { docName: 'me', backlinks: [] } },
+ });
+ const ctx = await loadWikiLinkContext('me');
+ expect(ctx.connectedDocNames.has('me')).toBe(false);
+ expect(autocompleteBoost('me', ctx)).toBe(50);
+ expect(autocompleteBoost('friend', ctx)).toBe(100);
+ });
+
+ test('degrades to the still-successful side when one endpoint errors (HTTP 500)', async () => {
+ stubLinks({
+ forward: { status: 500, body: {} },
+ back: {
+ body: {
+ docName: 'me',
+ backlinks: [{ source: 'in-b', anchor: null, title: 'B', snippet: null }],
+ },
+ },
+ });
+ const ctx = await loadWikiLinkContext('me');
+ expect(ctx.currentDocName).toBe('me');
+ expect([...ctx.connectedDocNames]).toEqual(['in-b']);
+ });
+
+ test('degrades to no neighbors when a response body is malformed', async () => {
+ stubLinks({ forward: { body: { wrong: 'shape' } }, back: { body: { nope: true } } });
+ const ctx = await loadWikiLinkContext('me');
+ expect(ctx.currentDocName).toBe('me');
+ expect(ctx.connectedDocNames.size).toBe(0);
+ });
+});
diff --git a/packages/app/src/editor/extensions/wiki-link-suggestion.ts b/packages/app/src/editor/extensions/wiki-link-suggestion.ts
index 8eaa4c034..629cebe89 100644
--- a/packages/app/src/editor/extensions/wiki-link-suggestion.ts
+++ b/packages/app/src/editor/extensions/wiki-link-suggestion.ts
@@ -1,7 +1,10 @@
import {
+ BacklinksSuccessSchema,
createWorkspaceSearchCorpus,
createWorkspaceSearchDocument,
+ ForwardLinksSuccessSchema,
type HeadingEntry,
+ MAX_WORKSPACE_SEARCH_LIMIT,
PageHeadingsSuccessSchema,
PagesSuccessSchema,
ProblemDetailsSchema,
@@ -15,6 +18,7 @@ import { ReactRenderer } from '@tiptap/react';
import Suggestion, { type SuggestionKeyDownProps, type SuggestionProps } from '@tiptap/suggestion';
import { HttpResponseParseError } from '../http-client';
import { WikiLinkSuggestionMenu } from '../wiki-link-suggestion/WikiLinkSuggestionMenu';
+import { getEditorDocName } from './doc-context';
import { getEditorSourceMode } from './editor-mode-context';
import {
createSuggestionPopup,
@@ -45,6 +49,37 @@ interface ParsedQuery {
const MAX_ITEMS = 8;
+export interface WikiLinkContext {
+ currentDocName: string | null;
+ connectedDocNames: ReadonlySet<string>;
+}
+
+const EMPTY_WIKI_LINK_CONTEXT: WikiLinkContext = {
+ currentDocName: null,
+ connectedDocNames: new Set(),
+};
+
+const SKILL_FOLDER_SEGMENTS: ReadonlySet<string> = new Set(['.agents', '.claude', '.cursor']);
+
+const SKILL_FOLDER_PENALTY = 200;
+const LINK_GRAPH_BOOST = 100;
+const CURRENT_PAGE_BOOST = 50;
+
+export function isSkillFolderDoc(docName: string): boolean {
+ return docName.split('/').some((segment) => SKILL_FOLDER_SEGMENTS.has(segment));
+}
+
+export function autocompleteBoost(docName: string, context: WikiLinkContext): number {
+ let boost = 0;
+ if (isSkillFolderDoc(docName)) boost -= SKILL_FOLDER_PENALTY;
+ if (context.currentDocName !== null && docName === context.currentDocName) {
+ boost += CURRENT_PAGE_BOOST;
+ } else if (context.connectedDocNames.has(docName)) {
+ boost += LINK_GRAPH_BOOST;
+ }
+ return boost;
+}
+
interface SuggestionSearchCorpus<T> {
fingerprint: string;
byPath: ReadonlyMap<string, T>;
@@ -66,14 +101,33 @@ export function parseQuery(query: string): ParsedQuery {
return { mode: 'page', pageTarget: '', anchorQuery: '' };
}
-export function filterPages(pages: PageItem[], query: string): PageItem[] {
- if (!query) return pages.slice(0, MAX_ITEMS);
+export function filterPages(
+ pages: PageItem[],
+ query: string,
+ context: WikiLinkContext = EMPTY_WIKI_LINK_CONTEXT,
+): PageItem[] {
+ if (!query) {
+ return pages
+ .map((page, index) => ({ page, index, boost: autocompleteBoost(page.docName, context) }))
+ .sort((a, b) => b.boost - a.boost || a.index - b.index)
+ .slice(0, MAX_ITEMS)
+ .map((entry) => entry.page);
+ }
const searchCorpus = getCachedPageSearchCorpus(pages);
return searchWorkspaceCorpus(searchCorpus.corpus, query, {
intent: 'autocomplete',
- limit: MAX_ITEMS,
+ limit: MAX_WORKSPACE_SEARCH_LIMIT,
})
- .map((result) => searchCorpus.byPath.get(result.document.path))
+ .map((result) => ({
+ result,
+ adjusted: result.score + autocompleteBoost(result.document.path, context),
+ }))
+ .sort(
+ (a, b) =>
+ b.adjusted - a.adjusted || a.result.document.path.localeCompare(b.result.document.path),
+ )
+ .slice(0, MAX_ITEMS)
+ .map((entry) => searchCorpus.byPath.get(entry.result.document.path))
.filter((page) => !!page);
}
@@ -132,8 +186,12 @@ export function filterHeadings(headings: HeadingEntry[], anchorQuery: string): H
.filter((heading) => !!heading);
}
-export function buildSuggestionItems(pages: PageItem[], query: string): WikiLinkSuggestionItem[] {
- const filtered = filterPages(pages, query);
+export function buildSuggestionItems(
+ pages: PageItem[],
+ query: string,
+ context: WikiLinkContext = EMPTY_WIKI_LINK_CONTEXT,
+): WikiLinkSuggestionItem[] {
+ const filtered = filterPages(pages, query, context);
if (filtered.length > 0) {
return filtered.map((item) =>
item.kind === 'asset'
@@ -289,10 +347,55 @@ export async function fetchHeadings(docName: string): Promise<HeadingEntry[]> {
return success.data.headings ?? [];
}
+async function fetchForwardLinkTargets(docName: string): Promise<string[]> {
+ try {
+ const r = await fetch(`/api/forward-links?docName=${encodeURIComponent(docName)}`);
+ if (!r.ok) {
+ console.warn('[wiki-link-suggestion] /api/forward-links responded', r.status, docName);
+ return [];
+ }
+ const success = ForwardLinksSuccessSchema.safeParse(await r.json());
+ if (!success.success) return [];
+ return success.data.forwardLinks.flatMap((link) => (link.kind === 'doc' ? [link.docName] : []));
+ } catch (err) {
+ console.warn('[wiki-link-suggestion] Failed to fetch forward links:', err);
+ return [];
+ }
+}
+
+async function fetchBacklinkSources(docName: string): Promise<string[]> {
+ try {
+ const r = await fetch(`/api/backlinks?docName=${encodeURIComponent(docName)}`);
+ if (!r.ok) {
+ console.warn('[wiki-link-suggestion] /api/backlinks responded', r.status, docName);
+ return [];
+ }
+ const success = BacklinksSuccessSchema.safeParse(await r.json());
+ if (!success.success) return [];
+ return success.data.backlinks.map((link) => link.source);
+ } catch (err) {
+ console.warn('[wiki-link-suggestion] Failed to fetch backlinks:', err);
+ return [];
+ }
+}
+
+export async function loadWikiLinkContext(currentDocName: string | null): Promise<WikiLinkContext> {
+ if (!currentDocName) return EMPTY_WIKI_LINK_CONTEXT;
+ const [outgoing, incoming] = await Promise.all([
+ fetchForwardLinkTargets(currentDocName),
+ fetchBacklinkSources(currentDocName),
+ ]);
+ const connectedDocNames = new Set<string>([...outgoing, ...incoming]);
+ connectedDocNames.delete(currentDocName);
+ return { currentDocName, connectedDocNames };
+}
+
export function configureWikiLinkSuggestion(editor: Editor) {
let cachedPages: PageItem[] = [];
let pagesLoaded = false;
let pagesPromise: Promise<PageItem[]> | null = null;
+ let cachedContext: WikiLinkContext = EMPTY_WIKI_LINK_CONTEXT;
+ let contextPromise: Promise<WikiLinkContext> | null = null;
let cachedHeadings = new Map<string, HeadingEntry[]>();
let anchorFetchingFor: string | null = null;
let fetchError: string | null = null;
@@ -330,20 +433,31 @@ export function configureWikiLinkSuggestion(editor: Editor) {
if (!pagesLoaded) {
pagesPromise ||= fetchPages();
- try {
- cachedPages = await pagesPromise;
+ contextPromise ||= loadWikiLinkContext(getEditorDocName(editor));
+ const [pagesResult, contextResult] = await Promise.allSettled([
+ pagesPromise,
+ contextPromise,
+ ]);
+ if (pagesResult.status === 'fulfilled') {
+ cachedPages = pagesResult.value;
fetchError = null;
- } catch (err) {
- console.error('[wiki-link-suggestion] Failed to fetch pages:', err);
+ } else {
+ console.error('[wiki-link-suggestion] Failed to fetch pages:', pagesResult.reason);
fetchError =
'Failed to load pages. Press Escape and type [[ again to retry, or continue typing to insert an unresolved link.';
cachedPages = [];
- } finally {
- pagesLoaded = true;
- pagesPromise = null;
}
+ if (contextResult.status === 'fulfilled') {
+ cachedContext = contextResult.value;
+ } else {
+ console.warn('[wiki-link-suggestion] link context load rejected:', contextResult.reason);
+ cachedContext = EMPTY_WIKI_LINK_CONTEXT;
+ }
+ pagesLoaded = true;
+ pagesPromise = null;
+ contextPromise = null;
}
- return buildSuggestionItems(cachedPages, query);
+ return buildSuggestionItems(cachedPages, query, cachedContext);
},
command: ({ editor, range, props: item }) => {
@@ -514,11 +628,13 @@ export function configureWikiLinkSuggestion(editor: Editor) {
currentProps = null;
selectedIndex = 0;
cachedPages = [];
+ cachedContext = EMPTY_WIKI_LINK_CONTEXT;
cachedHeadings = new Map();
fetchError = null;
anchorFetchError = null;
pagesLoaded = false;
pagesPromise = null;
+ contextPromise = null;
anchorFetchingFor = null;
},
};
diff --git a/packages/app/src/editor/plugins/wiki-link-source.ts b/packages/app/src/editor/plugins/wiki-link-source.ts
index ae537c02e..6143f95fa 100644
--- a/packages/app/src/editor/plugins/wiki-link-source.ts
+++ b/packages/app/src/editor/plugins/wiki-link-source.ts
@@ -16,7 +16,9 @@ import {
fetchPages,
filterHeadings,
filterPages,
+ loadWikiLinkContext,
type PageItem,
+ type WikiLinkContext,
} from '../extensions/wiki-link-suggestion';
import {
openHashHrefInNewTab,
@@ -30,6 +32,17 @@ let pagesCache: PageItem[] | null = null;
let pagesCacheTime = 0;
let knownTargetSet: Set<string> | null = null;
const headingsCache = new Map<string, { headings: HeadingEntry[]; time: number }>();
+const contextCache = new Map<string, { context: WikiLinkContext; time: number }>();
+
+async function getWikiLinkContext(docName: string | null): Promise<WikiLinkContext> {
+ if (!docName) return loadWikiLinkContext(null);
+ const now = Date.now();
+ const cached = contextCache.get(docName);
+ if (cached !== undefined && now - cached.time < PAGES_CACHE_TTL_MS) return cached.context;
+ const context = await loadWikiLinkContext(docName);
+ contextCache.set(docName, { context, time: now });
+ return context;
+}
async function getPages(): Promise<PageItem[]> {
const now = Date.now();
@@ -214,6 +227,7 @@ const wikiLinkClickHandler = EditorView.domEventHandlers({
async function wikiLinkCompletionSource(
context: CompletionContext,
+ currentDocName: string | null,
): Promise<CompletionResult | null> {
const textBefore = context.state.doc.sliceString(0, context.pos);
@@ -252,11 +266,14 @@ async function wikiLinkCompletionSource(
};
}
- const pages = await getPages().catch((err) => {
- console.warn('[wiki-link-source] Failed to fetch pages:', err);
- return [] as PageItem[];
- });
- const filtered = filterPages(pages, query);
+ const [pages, linkContext] = await Promise.all([
+ getPages().catch((err) => {
+ console.warn('[wiki-link-source] Failed to fetch pages:', err);
+ return [] as PageItem[];
+ }),
+ getWikiLinkContext(currentDocName),
+ ]);
+ const filtered = filterPages(pages, query, linkContext);
return {
from: triggerPos,
@@ -287,11 +304,14 @@ const wikiLinkTheme = EditorView.theme({
},
});
-export function createWikiLinkSourceExtension(): Extension {
+export function createWikiLinkSourceExtension(currentDocName: string | null = null): Extension {
return [
wikiLinkDecorations,
wikiLinkClickHandler,
wikiLinkTheme,
- markdownLanguage.data.of({ autocomplete: wikiLinkCompletionSource }),
+ markdownLanguage.data.of({
+ autocomplete: (context: CompletionContext) =>
+ wikiLinkCompletionSource(context, currentDocName),
+ }),
];
}