TanStack / TanStack/tanstack.com

Markdown link reference comments render as visible text in docs

Aperta
#1,015 0 commenti 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Lingua principale
TypeScript
Stelle
1.1k
Fork
401
Merge medio
18h 14m
PR unite (30g)
56

Descrizione

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.

Guida per i contributori

Nessuna guida per i contributori indicizzata per questo repository

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Direzione di ricerca

Inizia individuando la gestione delle definizioni dei riferimenti ai link in @tanstack/markdown e riproduci il problema con la pagina interessata della documentazione di TanStack Query. Verifica che le definizioni con destinazioni e titoli vengano omesse dall'output renderizzato, inclusa la forma [//]: # 'SomeLabel', mentre i normali riferimenti ai link continuino a essere renderizzati correttamente.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Valutazione

Stack tecnologico
markdown, typescript
Ambito
documentation, tooling
Tipo di issue
Bug
Difficoltà
3/5
Tempo stimato
1-2 giorni
Stato di attività
Tranquilla
Chiarezza
Specificata chiaramente
Idoneità per principianti
76/100

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.