TanStack / TanStack/tanstack.com
Markdown link reference comments render as visible text in docs
Nadie ha tomado este issue todavía.
- Lenguaje dominante
- TypeScript
- Estrellas
- 1.1k
- Forks
- 401
- Merge medio
- 18 h 14 min
- PR fusionados (30 d)
- 56
Descripción
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.
Guía de contribución
No hay ninguna guía de contribución indexada para este repositorio
Primeros pasos
- Lee el issue completo y luego la guía de contribución del proyecto.
- Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
- Haz un fork del repositorio y trabaja en una rama.
- Abre un pull request que haga referencia al número del issue.
Línea de trabajo
Empieza localizando el manejo de las definiciones de referencias de enlaces en @tanstack/markdown y reproduce el problema con la página afectada de la documentación de TanStack Query. Verifica que las definiciones con destinos y títulos se omitan de la salida renderizada, incluida la forma [//]: # 'SomeLabel', mientras que las referencias de enlaces normales siguen renderizándose correctamente.
Escrito por el modelo de indexación a partir del texto del issue.
Evaluación
- Stack tecnológico
- markdown, typescript
- Área
- documentation, tooling
- Tipo de issue
- Error
- Dificultad
- 3/5
- Tiempo estimado
- 1-2 días
- Estado de actividad
- Tranquilo
- Claridad
- Bien especificado
- Aptitud para principiantes
- 76/100