Markdown link reference comments render as visible text in docs
維護者通常 1 天內回覆
評估
- 難度
- 3/5
- 預估耗時
- 1-2 天
- 新手友好度
- 76/100
- Issue 類型
- 缺陷
- 描述清晰度
- 描述清楚
- 活躍度
- 冷清
- 技術堆疊
- markdown, typescript
- 領域
- documentation, tooling
研究方向
先定位 @tanstack/markdown 中對連結參照定義的處理，並使用受影響的 TanStack Query 文件頁面重現問題。確認帶有目的地和標題的定義會從轉譯輸出中省略，包括 [//]: # 'SomeLabel' 這種形式，同時一般的連結參照仍能正確轉譯。
由索引模型根據 Issue 內容生成。
描述
Describe the bug
Markdown comments written as link reference definitions with titles are rendering as visible text on the TanStack docs site.
For example, comments like this:
[//]: # 'SomeLabel'
appear visibly in the rendered docs page, but they are correctly hidden when previewing the same Markdown file on GitHub.
Affected scope
Any docs page generated from Markdown files that contain link reference comments with titles, for example:
https://tanstack.com/query/latest/docs/framework/react/guides/queries
This pattern appears to be used across many docs files, so the issue is not limited to a single page.
Expected behavior
The line should be parsed as a CommonMark link reference definition and omitted from rendered output, matching GitHub's Markdown preview behavior.
Actual behavior
The line is rendered as visible text in the docs page.
Why this matters
This pattern is used throughout the docs as invisible labels/anchors. In TanStack Query docs alone, many files use this syntax, so the issue can show up across multiple docs pages.
Likely root cause
The docs site appears to use @tanstack/markdown for parsing. Its link reference definition handling currently appears to only match definitions where the destination is the final token on the line:
const definition = line.match(/^ {0,3}\[([^\]\n]+)\]:[ \t]*(\S+)[ \t]*$/);
That does not match this valid CommonMark form:
[//]: # 'SomeLabel'
In this case, # is the destination and 'SomeLabel' is the optional title.
Suggested fix
Allow link reference definitions to include an optional title, matching CommonMark behavior:
const definition = line.match(
/^ {0,3}\[([^\]\n]+)\]:[ \t]*(\S+)(?:[ \t]+"[^"]*"|[ \t]+'[^']*'|[ \t]+\([^)]*\))?[ \t]*$/,
);
This would parse the example as a link reference definition and prevent it from being rendered as visible docs text.
- 主要語言
- TypeScript
- 星號
- 1.1k
- 分支
- 405
- 平均合併
- 5 小時 51 分鐘
- 30 天內合併 PR
- 58
環境準備
這個專案沒有提供開發容器、Dockerfile 或貢獻指南，環境需要你自己搭建：先看它的 README，通用步驟見我們的新手貢獻指南。
從這裡開始
- 先讀完整個 Issue，再讀專案的貢獻指南。
- 在 Issue 下留言說明你要接手 —— 這能避免兩個人做同樣的事。
- Fork 儲存庫，在一個分支上完成修改。
- 送出 Pull Request，並在描述裡引用這個 Issue 編號。
TanStack/tanstack.com 的其他 Issue
-
AI dock input submits on Enter during IME composition (Japanese/Chinese/Korean input)可能已有人在做 @Brightbong92 於 1 天前認領。 未關閉
難度 2/5 1-3 小時 新手友好度 68/100
TanStack/tanstack.com#1362 ·
維護者通常 1 天內回覆
-
Checkbox in dropdown doesn't scroll with items可能已有人在做 @6TELOIV 於 14 天前認領。 未關閉
難度 1/5 1 小時以內 新手友好度 92/100
TanStack/tanstack.com#1304 ·
維護者通常 1 天內回覆
-
"bundle report" link navigates to 404 on Markdown docs可能已有人在做 @lukonik 於 45 天前認領。 未關閉source-audit
難度 1/5 1 小時以內 新手友好度 84/100
TanStack/tanstack.com#1195 ·
維護者通常 1 天內回覆
-
source-audit
難度 2/5 1-3 小時 新手友好度 68/100
TanStack/tanstack.com#1194 · 2 則留言 ·
維護者通常 1 天內回覆
-
source-audit
難度 2/5 1-3 小時 新手友好度 72/100
TanStack/tanstack.com#1177 · 1 則留言 ·
維護者通常 1 天內回覆
查看 TanStack/tanstack.com 的全部 Issue
相似的 Issue
-
ai-driven-qa bug claude Minor
難度 2/5 1-3 小時 新手友好度 70/100
linagora/twake-contacts-frontend#241 ·
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 75/100
維護者通常 1 天內回覆
-
ui(ListToolbar): search takes the full row on a phone instead of sharing it with the result count未關閉
難度 2/5 1-3 小時 新手友好度 64/100
維護者通常 1 天內回覆
-
priority:high
難度 2/5 1-3 小時 新手友好度 72/100
維護者通常 1 天內回覆
-
難度 2/5 1-3 小時 新手友好度 70/100
ahmedkhaleel2004/gitdiagram#228 ·