docs: ITT-236 clarify issue mention Markdown (#3365)

apps/docs/content/docs/comments.mdx

@@ -37,6 +37,28 @@ Mentioning the same person multiple times in one comment still produces **only o
 **Use `@all` carefully.** In a larger workspace, a single `@all` generates that many inbox notifications instantly. Reserve it for things everyone genuinely needs to know — not day-to-day updates.
 </Callout>
 
+## Referencing issues
+
+To link another issue, type its issue key, such as `MUL-123`. Multica resolves real issue keys in comments and stores them as an internal `mention://issue/<uuid>` link. Issue links are cross-references only: they do not notify people and they do not trigger agents.
+
+You normally do not need to write `[MUL-123](mention://issue/<uuid>)` by hand. That format is the canonical internal representation after Multica has resolved the key.
+
+<Callout type="info">
+Markdown emphasis follows CommonMark rules. When bold text ends with punctuation or a closing quote and is immediately followed by a Korean particle, the closing `**` may not be recognized.
+
+Prefer moving the quote outside the bold span:
+
+```markdown
+"**무엇을 먼저 정해두고 시작할지**"가
+```
+
+instead of:
+
+```markdown
+**"무엇을 먼저 정해두고 시작할지"**가
+```
+</Callout>
+
 ## Editing and deleting a comment
 
 Only the author of a comment can edit or delete it.

apps/docs/content/docs/comments.zh.mdx

@@ -37,6 +37,28 @@ import { Callout } from "fumadocs-ui/components/callout";
 **谨慎使用 `@all`**。工作区人数较多时，一条 `@all` 的评论会瞬间生成同等数量的收件箱通知。只在确实需要全员知晓的重大事项上使用——不是日常琐事。
 </Callout>
 
+## 引用 issue
+
+要链接另一个 issue，直接输入它的 issue key，例如 `MUL-123`。Multica 会在评论中解析真实存在的 issue key，并把它存成内部的 `mention://issue/<uuid>` 链接。Issue 链接只是交叉引用：不会通知成员，也不会触发智能体。
+
+通常不需要手写 `[MUL-123](mention://issue/<uuid>)`。这是 Multica 解析 key 之后使用的内部规范格式。
+
+<Callout type="info">
+Markdown 加粗遵循 CommonMark 规则。当加粗文本以标点或闭引号结尾，并且后面紧跟韩语助词时，结尾的 `**` 可能不会被识别。
+
+推荐把引号放到加粗范围外：
+
+```markdown
+"**무엇을 먼저 정해두고 시작할지**"가
+```
+
+而不是：
+
+```markdown
+**"무엇을 먼저 정해두고 시작할지"**가
+```
+</Callout>
+
 ## 编辑和删除评论
 
 只有评论的作者能编辑或删除自己的评论。

packages/views/editor/extensions/mention-extension.test.ts

@@ -81,4 +81,12 @@ describe("mention tokenizer", () => {
     expect(token!.attributes.label).toBe("MUL-123");
     expect(token!.attributes.type).toBe("issue");
   });
+
+  it("finds an issue mention nested inside task list Markdown", () => {
+    const token = tokenize("- [ ] [MUL-123](mention://issue/aaa-bbb)");
+    expect(token).toBeDefined();
+    expect(token!.attributes.label).toBe("MUL-123");
+    expect(token!.attributes.type).toBe("issue");
+    expect(token!.attributes.id).toBe("aaa-bbb");
+  });
 });

packages/views/editor/readonly-content.test.tsx

@@ -126,6 +126,37 @@ describe("ReadonlyContent line breaks", () => {
   });
 });
 
+describe("ReadonlyContent issue mention Markdown", () => {
+  it("renders an issue mention inside a task list as an issue mention card", () => {
+    const { container, getByTestId } = render(
+      <ReadonlyContent content="- [ ] [MUL-123](mention://issue/issue-123)" />,
+    );
+
+    expect(container.querySelector('input[type="checkbox"]')).not.toBeNull();
+    expect(getByTestId("issue-mention-card").textContent).toBe("MUL-123");
+  });
+
+  it("documents the CommonMark quoted-emphasis edge case before Korean particles", () => {
+    const unsafe = render(
+      <ReadonlyContent content={'**"무엇을 먼저 정해두고 시작할지"**가'} />,
+    );
+
+    expect(unsafe.container.querySelector("strong")).toBeNull();
+    expect(unsafe.container.textContent).toContain(
+      '**"무엇을 먼저 정해두고 시작할지"**가',
+    );
+
+    const safe = render(
+      <ReadonlyContent content={'"**무엇을 먼저 정해두고 시작할지**"가'} />,
+    );
+
+    expect(safe.container.querySelector("strong")?.textContent).toBe(
+      "무엇을 먼저 정해두고 시작할지",
+    );
+    expect(safe.container.textContent).toContain('"무엇을 먼저 정해두고 시작할지"가');
+  });
+});
+
 describe("ReadonlyContent code styling", () => {
   const literalCode = "uv run --extra dev pytest -q";