Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

markdown comments improvements (#3961)

shagun-singh-inkeepee2ef7469d6f
diff --git a/.changeset/comment-rendering-split-runs.md b/.changeset/comment-rendering-split-runs.md
new file mode 100644
index 000000000..b66b5728f
--- /dev/null
+++ b/.changeset/comment-rendering-split-runs.md
@@ -0,0 +1,19 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Markdown comments now work when their body contains formatting, and they read as annotation instead of as punctuation.
+
+A comment written inline in a paragraph, `%%note%%` or `<!-- note -->`, was only recognized when its body was plain text. Put anything formatted inside it, bold, code, a link, and the comment stopped being a comment: the `%%` or `<!--` characters showed up as literal prose and the body rendered at full weight alongside the rest of the sentence, so an annotation read as part of the document. The cause was that formatting splits the surrounding text, which left the opening and closing delimiters too far apart for the recognizer to pair them. It now pairs them across the split, in paragraphs, headings, list items, and table cells alike.
+
+One byte-level consequence, for the HTML form only: a comment written without inner padding re-saves in the conventional `<!-- body -->` shape, the same way a plain-bodied one always has. The `%%` form keeps its body verbatim, spaces included.
+
+Recognition stays deliberately narrow. A paragraph, heading, or table cell carrying more than one candidate pair (its several lines share one budget), an escaped delimiter, a pair inside a code span, or a mid-sentence body that is nothing but a single formatted word is left as prose rather than guessed at, because claiming one of those would rewrite what you wrote the next time the file saved.
+
+The editor no longer prints the delimiters. A comment used to carry a literal `%%` or `<!--` on each side, and a standalone comment block carried a small marker naming it, so a paragraph with a few annotations in it was hard to read past the punctuation. Nothing else in the editor shows its own syntax: bold, code, and links all keep theirs out of the page. Comments now do the same. An inline comment is dimmed and italic under a dashed underline; a comment block is dimmed with a dashed left rail, which is what distinguishes it from a blockquote's solid one. The underline matters beyond decoration: without it a comment differed from ordinary emphasis by colour alone, and a reader who could not resolve that difference could publish text they meant to hide. The text itself is never hidden, because the same syntax can appear in prose you never meant as a comment. Source mode still shows the raw bytes, and that is where the delimiters are edited.
+
+On the choice to stop drawing them: Obsidian, whose `%%` syntax this is, does show the markers in its Live Preview — comments are the one exception to that mode's hide-the-syntax rule, and its users routinely add CSS to hide them. Obsidian reveals syntax near the cursor, which OpenKnowledge's block-canonical editing surface cannot replicate; a cursor-proximity reveal was tried here and set aside as too fidgety, so it is a not-now rather than a never. Reading views in both tools hide comments entirely.
+
+A related fix rides along in the `==highlight==` recognizer, which had the same defect: a highlight whose body contained formatting dropped backslash escapes from the prose around it, and an escaped `\==` pair following one was claimed anyway. Both now hold.
+
+Readers were never affected: wherever a document renders to HTML rather than to the editor, both forms come out as real HTML comments, which browsers do not display.
diff --git a/docs/content/features/editor.mdx b/docs/content/features/editor.mdx
index 158470553..6c9afa986 100644
--- a/docs/content/features/editor.mdx
+++ b/docs/content/features/editor.mdx
@@ -51,9 +51,13 @@ Notes that stay in the file and out of what a reader sees. (For review comments
| `<!-- note -->` | Everywhere. It's an HTML comment, so no markdown renderer ever shows it to a reader. |
| `%%note%%` | OpenKnowledge and Obsidian, which share the convention. Everywhere else it renders as ordinary text, percent signs and all. |
-So: reach for `<!-- -->` when the file will be read outside OpenKnowledge — pushed to GitHub, built into a docs site, opened in another editor. Reach for `%%…%%` when the file round-trips through Obsidian, whose own comment syntax this is. The syntax you type is the syntax that gets saved: OpenKnowledge never converts `<!-- -->` into `%%…%%` or back. A multi-line `%%` block is tidied to the padded shape, with a blank line after the opening delimiter and before the closing one.
+So: reach for `<!-- -->` when the file will be read outside OpenKnowledge — pushed to GitHub, built into a docs site, opened in another editor. Reach for `%%…%%` when the file round-trips through Obsidian, whose own comment syntax this is. The syntax you type is the syntax that gets saved: OpenKnowledge never converts `<!-- -->` into `%%…%%` or back. Two tidyings happen on save, and only these two. A multi-line `%%` block takes the padded shape, with a blank line after the opening delimiter and before the closing one. And an HTML comment gets one space of inner padding, so `<!--note-->` saves as `<!-- note -->`. The `%%` inline form keeps its body exactly as typed, spaces included.
-In the editor, comments stay visible and editable: dimmed and italic, with their delimiters drawn beside them, and a dashed left rail on the block form. That's deliberate — text you typed should never disappear from the surface you typed it into. Source mode shows the raw bytes, as always.
+In the editor, comments stay visible and editable: dimmed and italic under a dashed underline, with a dashed left rail on the block form. The underline is what tells a comment apart from ordinary emphasis without relying on colour. The delimiters themselves aren't drawn, the same way the editor doesn't draw the asterisks around bold — switch to source mode to see or edit them. That means the two forms look identical in the editor: which one a given comment uses is a real decision, per the table above, and source mode is where you check it. The body stays on screen either way, which is deliberate: text you typed should never disappear from the surface you typed it into.
+
+Two limits are worth knowing. The first applies mid-sentence only: a comment inside a line of prose whose body is *nothing but* a formatted word — `%%**bold**%%` — stays ordinary prose rather than becoming a comment, because there is no way to record whether the emphasis sat inside the comment or the comment inside the emphasis. Give it any plain text alongside (`%%note **bold**%%`) and it is recognized normally. The same comment alone on its own line is recognized either way, as a comment block.
+
+The second is a budget: a paragraph, heading, or table cell can carry **one** comment whose body contains formatting. Write two in the same one and neither is recognized — both stay literal `%%`, and worse, the word between them can be claimed as a comment instead and disappear from published output. Split them across separate paragraphs, or keep one of the two bodies plain.
Readers don't see them. Wherever OpenKnowledge renders a doc to HTML rather than to the editor, both forms come out as real HTML comments, which browsers don't display. Copying a passage out of OpenKnowledge leaves the comments behind too, so an annotation can't ride along into an email or a chat message. In-app read-only views — the rendered diff, the skill viewer — do keep showing them dimmed: there the whole point is to show you everything the document contains.
diff --git a/packages/app/src/globals.css b/packages/app/src/globals.css
index fcf660fb2..5fa666f1c 100644
--- a/packages/app/src/globals.css
+++ b/packages/app/src/globals.css
@@ -1479,74 +1479,54 @@
* delete typed text from the surface it was typed into. Reading surfaces
* still hide them — the mdast→hast renderer emits a literal HTML comment.
*
- * The delimiters are not in the document (the promoter strips them and
- * records the form as an attribute), so they are drawn as pseudo-elements.
- * That keeps them out of the text content ProseMirror maps positions
- * against and out of the serialized bytes. */
+ * No delimiter glyphs are drawn. Every other construct in this editor keeps
+ * its syntax out of the page — `**`, backticks and `[](…)` all live in
+ * attributes and render nothing — and a comment painting `%%` into the middle
+ * of a sentence was the one that didn't. Source mode shows the raw
+ * `%%…%%` / `<!-- … -->` bytes, which is where the delimiters are edited.
+ *
+ * Nothing names the construct to assistive technology: the mark renders a bare
+ * `span`, and no `role`, `aria-label` or `title` is attached anywhere.
+ *
+ * The dimming is paired with a SHAPE cue, per the house rule stated with the
+ * slash-token rules earlier in this file: a signal must never ride colour
+ * alone. Without one, an inline comment differed from `*emphasis*` by colour
+ * only — `em` gets no rule anywhere here, so it renders UA italic at
+ * `--foreground`, which means italic is on both and discriminates nothing.
+ * That matters more than it looks: a claimed run is emitted as a real HTML
+ * comment on reading surfaces, so "can I see the difference" is really "will
+ * readers see this text", and a reader who cannot resolve the step can publish
+ * away something they meant to hide.
+ *
+ * `underline dashed` specifically, for three reasons. It is the only line
+ * style still free inside `.ProseMirror` (`solid` is links, `dotted` is
+ * missing skill refs and the loading state, `wavy` is lint and unresolved
+ * refs; the other `dashed` belongs to the composer, a separate surface).
+ * Forced-colors mode forces `text-decoration-color` but preserves
+ * `-line` and `-style`, so the cue survives there with no media arm — unlike
+ * a background or box-shadow, which are suppressed. And it is the idiom this
+ * stylesheet already ships twice for the same "not ordinary prose" semantic.
+ *
+ * The delimiters themselves stay unpainted: the point was to stop printing a
+ * construct's syntax into the middle of a sentence, not to leave the construct
+ * unmarked. */
.comment-mark {
color: var(--muted-foreground);
font-style: italic;
+ text-decoration: underline dashed;
+ text-underline-offset: 3px;
}
-/* The delimiters are chrome, not prose. `content: "…" / ""` supplies an empty
- * alternative text so assistive technology does not read the punctuation out
- * as part of the sentence — `user-select: none` only governs mouse selection
- * and in-editor copy, it says nothing to AT. No extra opacity: these glyphs
- * are the only signifier that a run is an annotation, so dimming them below
- * the body they label put them under the 3:1 non-text contrast floor in the
- * light theme. */
-.comment-mark::before,
-.comment-mark::after {
- content: "%%" / "";
- font-style: normal;
- user-select: none;
-}
-
-.comment-mark[data-source-form="html"]::before {
- content: "<!--" / "";
- margin-right: 0.15em;
-}
-
-.comment-mark[data-source-form="html"]::after {
- content: "-->" / "";
- margin-left: 0.15em;
-}
-
-/* The block form needs an affordance the inline form gets from its delimiter
- * glyphs, and it has to stay distinguishable from a blockquote, which sits a
- * few rules below with its own muted left rail. A dashed rail plus a `%%`
- * marker in the gutter carries both: dashed reads as "not part of the prose"
- * where blockquote's solid rail reads as "quoted prose", and the marker names
- * the construct the way the inline glyphs do. */
.comment-block {
- position: relative;
color: var(--muted-foreground);
font-style: italic;
+ /* Dashed, where blockquote's rail a few rules below is solid: dashed reads as
+ * "not part of the prose", solid as "quoted prose". That contrast plus the
+ * dimming is the whole signal — the construct carries no gutter label, so the
+ * rail is what has to distinguish it. */
border-left: 2px dashed color-mix(in oklab, var(--muted-foreground) 45%, transparent);
padding-left: 0.75rem;
- margin: 0.5rem 0;
-}
-
-/* `background: inherit` rather than the page token so the knockout tracks the
- * local surface when the block sits inside a callout, a card, or a selection
- * highlight. The offset stays inside the block's own margin box so the marker
- * cannot collide with the previous line's descenders or clip when the block is
- * a first child. */
-.comment-block::before {
- content: "%%" / "";
- position: absolute;
- left: 0.35rem;
- top: -0.45em;
- font-style: normal;
- font-size: 0.7em;
- line-height: 1;
- padding: 0 0.15rem;
- background: inherit;
- user-select: none;
-}
-
-.comment-block[data-source-form="html"]::before {
- content: "<!--" / "";
+ margin: 0.6rem 0;
}
.ProseMirror .ok-find-match {
diff --git a/packages/app/tests/stress/comment-annotation-visibility.e2e.ts b/packages/app/tests/stress/comment-annotation-visibility.e2e.ts
index 61cb28a48..6b3671114 100644
--- a/packages/app/tests/stress/comment-annotation-visibility.e2e.ts
+++ b/packages/app/tests/stress/comment-annotation-visibility.e2e.ts
@@ -18,7 +18,9 @@
import { expect, test, waitForActiveProviderSynced } from './_helpers';
const SEED = [
- 'Ordinary prose above.',
+ 'Ordinary prose above with *plain emphasis* in it.',
+ '',
+ '> An ordinary blockquote.',
'',
'A sentence with %%an inline percent note%% inside it.',
'',
@@ -73,16 +75,51 @@ test('promoted comment annotations render visibly, not hidden', async ({ page, a
expect(computed.opacity).toBeGreaterThan(0);
}
- // The delimiter glyphs are the affordance that names the construct, and they
- // are pseudo-element content — invisible to `textContent`, so assert them
- // where they live.
- const inlineGlyph = await inlineMark.evaluate(
- (element) => getComputedStyle(element, '::before').content,
- );
- expect(inlineGlyph).toContain('%%');
+ // With no delimiter glyphs, the dimming and the italic ARE the affordance
+ // that names an inline annotation, so this tier has to prove they survive
+ // the compiled cascade. Comparing against the surrounding prose rather than
+ // against the token: a rule that resolved `--muted-foreground` to the body
+ // colour would satisfy a token assertion while leaving the run
+ // indistinguishable from the sentence it sits in.
+ const inlineStyle = await inlineMark.evaluate((element) => {
+ const own = getComputedStyle(element);
+ return {
+ color: own.color,
+ fontStyle: own.fontStyle,
+ textDecorationLine: own.textDecorationLine,
+ };
+ });
+ const emStyle = await page
+ .locator('.ProseMirror em')
+ .first()
+ .evaluate((element) => {
+ const own = getComputedStyle(element);
+ return {
+ color: own.color,
+ fontStyle: own.fontStyle,
+ textDecorationLine: own.textDecorationLine,
+ };
+ });
+
+ // Compared against `em`, not against the comment's own container: `em` is
+ // what an inline comment is actually confusable with (both italic, both
+ // inline), and a rule that dimmed BOTH would satisfy a self-comparison while
+ // leaving them indistinguishable.
+ expect(inlineStyle.fontStyle).toBe('italic');
+ expect(emStyle.fontStyle).toBe('italic');
+ expect(inlineStyle.color).not.toBe(emStyle.color);
+ // Colour must not be the only discriminator (WCAG 1.4.1): the two have to
+ // differ on a channel that survives forced colors, where `color` does not.
+ expect(inlineStyle.textDecorationLine).not.toBe(emStyle.textDecorationLine);
+ expect(inlineStyle.textDecorationLine).toContain('underline');
// The annotation must not be confusable with the blockquote that shares the
// muted-left-rail treatment a few rules away in the same stylesheet.
const blockBorder = await block.evaluate((element) => getComputedStyle(element).borderLeftStyle);
+ const quoteBorder = await page
+ .locator('.ProseMirror blockquote')
+ .first()
+ .evaluate((element) => getComputedStyle(element).borderLeftStyle);
expect(blockBorder).toBe('dashed');
+ expect(blockBorder).not.toBe(quoteBorder);
});
diff --git a/packages/core/src/extensions/comment-mark.ts b/packages/core/src/extensions/comment-mark.ts
index f73bcf026..307e72db7 100644
--- a/packages/core/src/extensions/comment-mark.ts
+++ b/packages/core/src/extensions/comment-mark.ts
@@ -9,6 +9,14 @@
* `comment-mark` class the app styles as dimmed annotation. Source mode
* (CodeMirror) shows the literal `%%…%%` / `<!-- … -->` bytes.
*
+ * The WYSIWYG draws no delimiters of its own. Every other construct in this
+ * schema keeps its syntax in an attribute and renders none of it
+ * (`sourceDelimiter` on emphasis, `sourceFenceChar` on code); a comment is the
+ * same. The app marks the run with dimming plus a dashed underline instead —
+ * the underline is load-bearing, not decoration, since dimming alone leaves a
+ * comment differing from `*emphasis*` by colour only. Delimiters are edited in
+ * source mode.
+ *
* The mark deliberately does NOT hide the run in the editing surface. The
* promoter claims literal comment syntax wherever it appears, including
* prose a user typed without meaning it as a comment, so hiding the run
@@ -39,9 +47,10 @@
* `sourceLiteral` — the mark doesn't extend into trailing typed input.
*
* Schema name `comment` is unique in the workspace (no prior PM mark with
- * this name; no upstream TipTap collision). Style hooks key off
- * `data-comment-mark` so app/docs CSS layers can swap the visual treatment
- * without touching the mark schema.
+ * this name; no upstream TipTap collision). Style hooks key off the
+ * `comment-mark` CLASS — no stylesheet targets `data-comment-mark`, which
+ * exists for `parseHTML` round-trip and as a DOM/test locator, while
+ * `data-clipboard-omit` carries clipboard omission.
*/
import { Mark } from '@tiptap/core';
diff --git a/packages/core/src/markdown/comment-promoter.ts b/packages/core/src/markdown/comment-promoter.ts
index 7415c474a..e3a4af858 100644
--- a/packages/core/src/markdown/comment-promoter.ts
+++ b/packages/core/src/markdown/comment-promoter.ts
@@ -57,6 +57,8 @@ export function commentPromoterPlugin() {
arr.splice(index, 1, ...replacements);
return [SKIP, index + replacements.length];
});
+
+ promoteSpanningInlineComments(tree, source);
};
}
@@ -387,3 +389,222 @@ function isFenceOnlyParagraph(p: Paragraph, source: string): boolean {
if (text.trim() !== '%%') return false;
return !runEscaped(source, p.children[0] as Text, text.indexOf('%%'), 2);
}
+
+function promoteSpanningInlineComments(tree: Root, source: string): void {
+ if (source.indexOf('%%') === -1 && source.indexOf('<!--') === -1) return;
+
+ visit(tree, (node) => {
+ if (!SPANNING_PARENT_TYPES.has(node.type)) return;
+ const children = (node as { children?: PhrasingContent[] }).children;
+ if (children === undefined || children.length < 2) return;
+ for (const spec of SPANNING_FORMS) {
+ if (promoteSpanningForm(children, source, spec)) return;
+ }
+ });
+}
+
+const SPANNING_PARENT_TYPES: ReadonlySet<string> = new Set(['paragraph', 'heading', 'tableCell']);
+
+interface SpanningFormSpec {
+ sourceForm: 'percent' | 'html';
+ open: string;
+ close: string;
+}
+
+const SPANNING_FORMS: readonly SpanningFormSpec[] = [
+ { sourceForm: 'html', open: '<!--', close: '-->' },
+ { sourceForm: 'percent', open: '%%', close: '%%' },
+];
+
+interface DelimiterHit {
+ index: number;
+ offset: number;
+}
+
+function collectDelimiterHits(children: readonly PhrasingContent[], token: string): DelimiterHit[] {
+ const hits: DelimiterHit[] = [];
+ for (let i = 0; i < children.length; i++) {
+ const child = children[i];
+ if (child.type !== 'text') continue;
+ let from = 0;
+ while (true) {
+ const at = child.value.indexOf(token, from);
+ if (at === -1) break;
+ hits.push({ index: i, offset: at });
+ from = at + token.length;
+ }
+ }
+ return hits;
+}
+
+function promoteSpanningForm(
+ children: PhrasingContent[],
+ source: string,
+ spec: SpanningFormSpec,
+): boolean {
+ let open: DelimiterHit;
+ let close: DelimiterHit;
+
+ if (spec.sourceForm === 'percent') {
+ const hits = collectDelimiterHits(children, '%%');
+ if (hits.length !== 2) return false;
+ [open, close] = hits;
+ } else {
+ const opens = collectDelimiterHits(children, '<!--');
+ const closes = collectDelimiterHits(children, '-->');
+ if (opens.length !== 1 || closes.length !== 1) return false;
+ open = opens[0];
+ close = closes[0];
+ }
+
+ if (open.index >= close.index) return false;
+
+ const openChild = children[open.index] as Text;
+ const closeChild = children[close.index] as Text;
+
+ if (spec.sourceForm === 'percent') {
+ if (openChild.value[open.offset - 1] === '%') return false;
+ if (openChild.value[open.offset + 2] === '%') return false;
+ if (closeChild.value[close.offset - 1] === '%') return false;
+ if (closeChild.value[close.offset + 2] === '%') return false;
+ }
+
+ if (spanCrossesLineBreak(children, spec, open, close)) return false;
+
+ if (runEscaped(source, openChild, open.offset, spec.open.length)) return false;
+ if (runEscaped(source, closeChild, close.offset, spec.close.length)) return false;
+
+ for (let i = open.index + 1; i < close.index; i++) {
+ if (containsClaimedComment(children[i])) return false;
+ }
+
+ if (open.offset === 0 && containsClaimedComment(children[open.index - 1])) return false;
+ if (
+ close.offset + spec.close.length === closeChild.value.length &&
+ containsClaimedComment(children[close.index + 1])
+ ) {
+ return false;
+ }
+
+ const body = buildSpanningBody(children, spec, open, close, source);
+ if (body === null) return false;
+
+ const replacements: PhrasingContent[] = [];
+ const lead = openChild.value.slice(0, open.offset);
+ if (lead.length > 0) replacements.push(sliceTextNode(source, openChild, 0, open.offset));
+
+ const commentNode: CommentMdast = {
+ type: 'comment',
+ children: body,
+ data: { sourceForm: spec.sourceForm },
+ };
+ const openPos = deriveFragmentPosition(source, openChild, open.offset, openChild.value.length);
+ const closePos = deriveFragmentPosition(source, closeChild, 0, close.offset + spec.close.length);
+ if (openPos && closePos) {
+ commentNode.position = { start: openPos.start, end: closePos.end };
+ }
+ replacements.push(commentNode as unknown as PhrasingContent);
+
+ const tailFrom = close.offset + spec.close.length;
+ const tail = closeChild.value.slice(tailFrom);
+ if (tail.length > 0) {
+ replacements.push(sliceTextNode(source, closeChild, tailFrom, closeChild.value.length));
+ }
+
+ children.splice(open.index, close.index - open.index + 1, ...replacements);
+ return true;
+}
+
+function buildSpanningBody(
+ children: readonly PhrasingContent[],
+ spec: SpanningFormSpec,
+ open: DelimiterHit,
+ close: DelimiterHit,
+ source: string,
+): PhrasingContent[] | null {
+ const openChild = children[open.index] as Text;
+ const closeChild = children[close.index] as Text;
+
+ let headFrom = open.offset + spec.open.length;
+ const headTo = openChild.value.length;
+ const footFrom = 0;
+ let footTo = close.offset;
+
+ if (spec.sourceForm === 'html') {
+ while (headFrom < headTo && /\s/.test(openChild.value[headFrom])) headFrom += 1;
+ while (footTo > footFrom && /\s/.test(closeChild.value[footTo - 1])) footTo -= 1;
+ }
+
+ const body: PhrasingContent[] = [];
+ if (headFrom < headTo) {
+ body.push(sliceTextNode(source, openChild, headFrom, headTo));
+ }
+ for (let i = open.index + 1; i < close.index; i++) body.push(children[i]);
+ if (footFrom < footTo) {
+ body.push(sliceTextNode(source, closeChild, footFrom, footTo));
+ }
+
+ if (body.length === 0) return null;
+
+ const hasContent = body.some((child) =>
+ child.type === 'text' ? child.value.trim().length > 0 : true,
+ );
+ if (!hasContent) return null;
+
+ if (!body.some((child) => child.type === 'text')) return null;
+
+ return body;
+}
+
+function spanCrossesLineBreak(
+ children: readonly PhrasingContent[],
+ spec: SpanningFormSpec,
+ open: DelimiterHit,
+ close: DelimiterHit,
+): boolean {
+ const openChild = children[open.index] as Text;
+ const closeChild = children[close.index] as Text;
+ if (openChild.value.indexOf('\n', open.offset + spec.open.length) !== -1) return true;
+ if (closeChild.value.lastIndexOf('\n', close.offset) !== -1) return true;
+ for (let i = open.index + 1; i < close.index; i++) {
+ if (containsLineBreak(children[i])) return true;
+ }
+ return false;
+}
+
+function containsLineBreak(node: unknown): boolean {
+ const typed = node as { type?: string; value?: string; children?: unknown };
+ if (typed?.type === 'break') return true;
+ if (typed?.type === 'text') return (typed.value ?? '').indexOf('\n') !== -1;
+ return Array.isArray(typed?.children) && typed.children.some(containsLineBreak);
+}
+
+function containsClaimedComment(node: unknown): boolean {
+ if (node === undefined || node === null) return false;
+ if ((node as { type?: string }).type === 'comment') return true;
+ const kids = (node as { children?: unknown }).children;
+ return Array.isArray(kids) && kids.some(containsClaimedComment);
+}
+
+interface EntityRefSpan {
+ offset: number;
+ length: number;
+ raw: string;
+}
+
+function sliceTextNode(source: string, node: Text, from: number, to: number): Text {
+ const sliced: Text = { type: 'text', value: node.value.slice(from, to) };
+
+ const pos = deriveFragmentPosition(source, node, from, to);
+ if (pos) sliced.position = pos;
+
+ const spans = (node.data as { entityRefSpans?: EntityRefSpan[] } | undefined)?.entityRefSpans;
+ if (spans?.length) {
+ const inside = spans
+ .filter((span) => span.offset >= from && span.offset + span.length <= to)
+ .map((span) => ({ ...span, offset: span.offset - from }));
+ if (inside.length > 0) sliced.data = { entityRefSpans: inside } as Text['data'];
+ }
+
+ return sliced;
+}
diff --git a/packages/core/src/markdown/highlight-promoter.ts b/packages/core/src/markdown/highlight-promoter.ts
index da0a81d23..ee6d25fda 100644
--- a/packages/core/src/markdown/highlight-promoter.ts
+++ b/packages/core/src/markdown/highlight-promoter.ts
@@ -51,8 +51,12 @@ interface EntityRefSpan {
raw: string;
}
-function sliceTextNode(source: Text, from: number, to: number): Text {
+function sliceTextNode(source: Text, from: number, to: number, rawSource?: string): Text {
const out: Text = { type: 'text', value: source.value.slice(from, to) };
+ if (rawSource !== undefined) {
+ const pos = deriveFragmentPosition(rawSource, source, from, to);
+ if (pos) out.position = pos;
+ }
const spans = (source.data as { entityRefSpans?: EntityRefSpan[] } | undefined)?.entityRefSpans;
if (spans?.length) {
const inside = spans
@@ -180,10 +184,10 @@ function promoteCrossChildren(parent: Parent, source: string): void {
const bodyChildren: PhrasingContent[] = [];
if (openTrailing.length > 0) {
- bodyChildren.push(sliceTextNode(openChild, openPos + 2, openValue.length));
+ bodyChildren.push(sliceTextNode(openChild, openPos + 2, openValue.length, source));
}
for (let k = outerI + 1; k < closeChildIdx; k++) bodyChildren.push(children[k]);
- if (closeLeading.length > 0) bodyChildren.push(sliceTextNode(closeChild, 0, closePos));
+ if (closeLeading.length > 0) bodyChildren.push(sliceTextNode(closeChild, 0, closePos, source));
if (!bodyCrossesInline) {
outerI++;
@@ -196,10 +200,10 @@ function promoteCrossChildren(parent: Parent, source: string): void {
};
const replacement: PhrasingContent[] = [];
- if (leadValue.length > 0) replacement.push(sliceTextNode(openChild, 0, openPos));
+ if (leadValue.length > 0) replacement.push(sliceTextNode(openChild, 0, openPos, source));
replacement.push(markNode as unknown as PhrasingContent);
if (tailValue.length > 0) {
- replacement.push(sliceTextNode(closeChild, closePos + 2, closeChild.value.length));
+ replacement.push(sliceTextNode(closeChild, closePos + 2, closeChild.value.length, source));
}
children.splice(outerI, closeChildIdx - outerI + 1, ...replacement);
diff --git a/packages/server/assets/skills/project/references/components-and-visuals.md b/packages/server/assets/skills/project/references/components-and-visuals.md
index 5780fe7b7..6bb4be1e5 100644
--- a/packages/server/assets/skills/project/references/components-and-visuals.md
+++ b/packages/server/assets/skills/project/references/components-and-visuals.md
@@ -11,7 +11,7 @@ OK auto-promotes markdown-native syntax into themed canonical components at pars
| Diagram | a ` ```mermaid ` fenced block (flowchart, sequence, class, state, ER, gantt, pie) — label-text pitfalls + escapes: `palette({ components: ["Mermaid"] })`; parse failures come back as `warnings` entries on write/edit | Mermaid diagram |
| Math | `$x$` inline, `$$…$$` block | KaTeX Math |
| Highlight | `==text==` | highlight mark |
-| Author-only comment (hidden from readers) | `%%text%%` or `<!-- text -->` | comment mark |
+| Author-only comment (hidden from readers) | `%%text%%` or `<!-- text -->` (mid-sentence, a body that is only a formatted word, `%%**bold**%%`, stays prose — pair it with plain text; alone on a line it is fine) | comment mark |
| Inline a doc or asset | `![[file]]` | wiki embed |
**These delimiters are live in ordinary prose.** `==`, `$`, `$$`, `%%`, `<!--` … `-->` and `~~` format — or hide — whatever sits between them, wherever they appear, not only where you meant them as syntax. To show a literal pair, wrap it in an inline code span (`` `==x==` ``, `` `$5` ``), which always works and reads as code; or backslash-escape a delimiter to keep it as running prose. Escaping either side is enough for `==`, `$`, `%%` and `<!--`: `\==x\==`, `\$5`, `\%\%note\%\%`, `\<!-- note -->`. For `~~`, escape both tildes (`\~\~x\~\~`) — a one-sided `\~~x~~` renders right but gets rewritten to the two-sided form on save. Watch `%%` and `<!-- -->` in particular: an accidental pair doesn't restyle the text, it hides it.