TanStack / TanStack/tanstack.com

Markdown link reference comments render as visible text in docs

Open
#1,015 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
TypeScript
Stars
1.1k
Forks
401
Avg merge
18h 14m
Merged PRs (30d)
56

Description

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:

Image

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.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by locating link reference definition handling in @tanstack/markdown and reproduce the issue with the affected TanStack Query docs page. Verify that definitions with destinations and titles are omitted from rendered output, including the [//]: # 'SomeLabel' form, while ordinary link references still render correctly.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, typescript
Domain
documentation, tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Clearly specified
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.