Hacktoberfest 2026: as issues que os mantenedores marcaram para outubro, abertas e boas para iniciantes. Ver issues do Hacktoberfest

Markdown link reference comments render as visible text in docs

Aberta
#1,015 0 comentários 0 reações 0 responsáveis Ver no GitHub

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
3/5
Tempo estimado
1-2 dias
Facilidade para iniciantes
76/100
Tipo de issue
Bug
Clareza
Claramente especificada
Status de atividade
Pouca atividade
Stack de tecnologia
markdown, typescript
Domínio
documentation, tooling

Direção de pesquisa

Comece localizando o tratamento das definições de referência de links em @tanstack/markdown e reproduza o problema com a página afetada da documentação do TanStack Query. Verifique se as definições com destinos e títulos são omitidas da saída renderizada, incluindo a forma [//]: # 'SomeLabel', enquanto as referências de links comuns continuam sendo renderizadas corretamente.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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.

Linguagem predominante
TypeScript
Estrelas
1.1k
Forks
401
Merge médio
16h 8min
PRs com merge (30d)
58

Guia de contribuição

Nenhum guia de contribuição indexado para este repositório

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de TanStack/tanstack.com

Todas as issues de TanStack/tanstack.com

Issues semelhantes

Mais issues de TypeScript

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.