Links e Tooltips de Termos do Glossário: Regras de Redação

Um link de termo do glossário conecta um termo em sua primeira menção significativa à única página que possui sua definição completa. O link ajuda o leitor a compreender linguagem desconhecida sem interromper o artigo e fornece aos rastreadores uma relação consistente entre o termo e sua página de entidade canônica.

Um URL canônico é a versão preferida de uma página quando várias URLs contêm o mesmo conteúdo ou conteúdo substancialmente similar.

Essa frase é o elemento em ação. A âncora é o termo exato, o destino é sua entrada canônica no glossário, e a frase ao redor permanece compreensível sem abrir o link. Em sistemas que suportam, o mesmo link pode exibir uma tooltip de definição curta ao passar o mouse ou ao receber foco do teclado. A página vinculada — não a tooltip — continua sendo a fonte da verdade.

Por que este elemento é importante

Os leitores não chegam com o mesmo vocabulário. Um especialista pode reconhecer “URL canônico” imediatamente, enquanto um comprador ou novo membro da equipe pode precisar de uma definição. Explicar cada termo entre parênteses torna a prosa lenta para especialistas; não explicar nenhum exclui os novatos. Um link de termo do glossário cria uma saída de emergência silenciosa: continue se o termo for familiar, ou abra sua definição se não for.

A regra da primeira menção é importante porque a incerteza se acumula. Se um leitor interpretar mal um termo no segundo parágrafo, todas as afirmações posteriores baseadas naquele termo serão mais difíceis de avaliar. Vincular a primeira ocorrência significativa resolve a incerteza antes que ela se espalhe. A regra não significa “vincule a primeira correspondência de string”. Um termo em um título, rótulo de navegação, exemplo de código ou texto de prévia pode ainda não carregar o significado usado na explicação.

A extraibilidade por máquina é a capacidade do software de preservar uma relação após a remoção da apresentação. Uma âncora descritiva e um destino estável criam uma aresta explícita: esta página usa o conceito, e aquela página de glossário o define. Arestas consistentes reforçam qual URL possui a definição. Elas não criam um grafo de conhecimento formal nem garantem visibilidade, mas reduzem a ambiguidade que um rastreador resolveria apenas pela proximidade.

O excesso de links reverte esses benefícios. Quando cada termo repetido tem link, a página para de sinalizar prioridade. Os leitores enfrentam um campo de saídas concorrentes, usuários de tecnologia assistiva ouvem o mesmo destino repetidamente e as máquinas recebem muitas arestas redundantes em vez de um pequeno conjunto de relações deliberadas. Um link canônico na primeira menção significativa é, portanto, o padrão, não um mínimo a ser repetido em cada seção.

Quando usar

Use o elemento quando todas as três condições forem verdadeiras:

1. O termo possui uma página de glossário canônica, em vez de várias definições quase duplicadas.
2. Compreender o termo ajuda materialmente o leitor a entender a página atual.
3. O primeiro uso significativo pode conter uma âncora descritiva sem distorcer a frase.

Bons candidatos incluem terminologia especializada, siglas em seu primeiro uso expandido, normas nomeadas, métricas e palavras cujo significado no domínio difere do uso cotidiano. Uma tooltip pode pré-visualizar uma definição curta; a página completa do glossário trata dos limites, exemplos, fontes e termos relacionados.

Os casos limítrofes são onde o elemento é mais frequentemente mal utilizado:

• Vocabulário comum: não vincule uma palavra familiar apenas porque existe uma entrada no glossário.
• Menções incidentais: se o artigo nomeia um conceito mas não depende dele, um link cria uma saída desnecessária.
• Menções repetidas: após o primeiro uso vinculado, deixe o termo como texto, a menos que uma página longa e multipartes crie um contexto de leitura genuinamente independente.
• Texto de âncora ambíguo: “esta abordagem”, “saiba mais” e “a métrica” não identificam a entidade do glossário. Vincule o próprio termo.
• Nenhum destino canônico: não substitua por um resultado de pesquisa, arquivo de tags ou artigo vagamente relacionado. Use prosa simples até que a definição canônica exista.
• Definição já fornecida por completo: se o glossário não adiciona profundidade útil, um desvio definicional extra pode ser desnecessário.
• Direcionamento comercial: um link de glossário não é um chamado para ação disfarçado de produto. Páginas de produto, fluxos de cadastro e páginas de preço atendem a intenções diferentes do leitor.

Aplique as regras de redação de elementos compartilhadas antes de improvisar. A regra de precedência exige que os autores selecionem um elemento por propósito. Se o propósito é conectar um termo nomeado à sua definição canônica, use esta relação tipificada em vez de um link inline genérico estilizado para parecer similar.

Onde posicionar

Posicione o link na primeira menção significativa em prosa: a primeira frase que usa o conceito no sentido do destino. Se o termo aparecer primeiro no título ou em um H2, crie o link em seu primeiro uso no parágrafo seguinte. Os cabeçalhos devem permanecer como rótulos de seção estáveis, em vez de grandes alvos de navegação.

Para uma sigla, escreva o termo completo seguido da abreviação e vincule o termo completo: geração aumentada por recuperação (RAG). Ocorrências posteriores podem usar RAG sem link.

Não posicione um link de termo do glossário:

• dentro de outro link, botão ou cartão clicável;
• ao lado de um segundo link sobre o mesmo texto de âncora;
• em código, URL, endereço de e-mail ou texto literal inserido pelo usuário;
• em um cabeçalho apenas para satisfazer a regra da primeira menção;
• em todas as linhas de uma tabela quando uma definição vinculada na introdução pode estabelecer o termo;
• imediatamente ao lado de um marcador de citação se os dois alvos se tornarem visual ou operacionalmente indistinguíveis;
• dentro de um gatilho de tooltip separado do link real.

Se uma frase contiver vários termos desconhecidos, vincule apenas os termos necessários para entender aquela frase. Três ou mais links de glossário em uma frase são um aviso de que a prosa assume vocabulário demais. Reescreva a frase, defina um conceito no local ou divida a explicação antes de adicionar mais saídas.

Anatomia

O espécime rotulado tem seis regiões:

1. Âncora do termo: o termo visível ou nome expandido completo, sem “saiba mais”.
2. Destino canônico: um URL de glossário estável que possui a definição.
3. Frase de contexto: prosa suficiente para entender por que o termo aparece, mesmo que o link não seja aberto.
4. Estilização do link: o tratamento padrão de link inline do site; a cor não é o único indicador.
5. Indicador de foco: um estado de teclado visível que não é cortado pelo parágrafo ou tooltip.
6. Tooltip opcional: uma prévia breve vinculada ao próprio link, nunca um controle separado apenas com ícone.

A apresentação pode mudar sem alterar a âncora, o destino ou o comportamento de primeira menção.

Exemplos de design

Cada variante preserva o mesmo link semântico.

Link inline padrão: a linha de base obrigatória. Funciona com JavaScript desabilitado, no modo leitor, em anotações de impressão e em dispositivos sem hover.

Tooltip de definição ao focar ou passar o mouse: um aprimoramento para conteúdo educacional denso. A prévia tem uma ou duas frases e nunca contém links, botões, citações ou controles de formatação.

Mobile e toque: o primeiro toque segue o link, a menos que o produto tenha um padrão de divulgação estabelecido e acessível. Não force os usuários a descobrir que um toque abre uma prévia e um segundo toque navega, a menos que essa interação seja consistente em todo o site e claramente comunicada.

Fundo escuro: link, anel de foco, texto da tooltip e borda da tooltip mantêm contraste claro. Não remova o sublinhado apenas porque a cor de destaque é brilhante.

Parâmetros

O URL canônico e a âncora visível são decisões de conteúdo. O comportamento da tooltip pertence ao renderizador. Separar essas fontes impede que um recurso de interface opcional altere o significado do link.

Nunca infira href a partir de term: homônimos podem compartilhar a grafia e exigir destinos diferentes. Obtenha uma tooltip do registro do glossário apenas quando sua definição curta for revisada para uso fora da página.

Sintaxe e exemplos de código

Todos os três formatos preservam um link normal como núcleo. Os campos nomeados são um contrato portátil; uma plataforma pode renderizá-los com um bloco nativo, plugin ou etapa de pré-processamento.

Diretiva Markdown portátil

The :::glossary-link{href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true"}canonical URL::: consolidates signals on the preferred page.

Se o pipeline de publicação não suportar diretivas inline, use Markdown comum e omita a tooltip:

The [canonical URL](/glossary/canonical-url/) consolidates signals on the preferred page.

Shortcode Hugo

The {{< glossary-term-link href="/glossary/canonical-url/" definition="A canonical URL is the preferred version of a page when duplicate or similar URLs exist." tooltip="true" >}}canonical URL{{< /glossary-term-link >}} consolidates signals on the preferred page.

Esta notação especifica o mapeamento necessário; não exige que autores introduzam um novo shortcode em um projeto que já lida com links de glossário por meio de renderização Markdown ou pré-processamento de conteúdo. O fallback renderizado deve ser sempre um elemento <a href> comum.

WordPress

<!-- wp:amicited/glossary-link {"href":"/glossary/canonical-url/","definition":"A canonical URL is the preferred version of a page when duplicate or similar URLs exist.","tooltip":true} -->
<a href="/glossary/canonical-url/">canonical URL</a>
<!-- /wp:amicited/glossary-link -->

O conteúdo exportado deve manter a âncora e o href mesmo quando os metadados da tooltip estiverem indisponíveis.

Exemplos

Bom

Selecione um URL canônico para páginas substancialmente similares, de modo que os sinais de indexação apontem para a versão preferida.

No artigo renderizado, “URL canônico” tem link para /glossary/canonical-url/ neste primeiro uso significativo. A âncora nomeia a entidade exatamente, a frase fornece contexto local suficiente para continuar a leitura, e ocorrências posteriores permanecem como texto simples. O leitor pode escolher se a definição completa é necessária.

Ruim

Selecione uma página preferida para páginas similares. Seu URL canônico deve então referenciar o URL canônico em cada seção.

Isso falha duas vezes. “Página preferida” é uma expressão relacionada, mas não o termo exato que o destino define, então a relação é menos explícita. Repetir o link do URL canônico em cada seção adiciona saídas sem adicionar significado. A correção correta é vincular “URL canônico” uma vez no primeiro uso significativo e deixar os usos posteriores sem link.

Outro padrão ruim é um ícone de informação após um termo sem link. O ícone esconde o destino dos leitores que examinam o texto do link, cria um alvo de toque pequeno e pode separar a tooltip da relação navegável do glossário.

Marcação Schema e acessibilidade

Um link de termo do glossário não precisa de um tipo Schema.org independente. Ele permanece um link dentro do Article, TechArticle ou WebPage que o contém. Não fabrique marcação DefinedTerm, mentions ou about para cada link inline; adicione tais relações apenas por meio de um modelo de dados consistente no nível da página, justificado pelo conteúdo visível.

A acessibilidade começa com uma âncora real. Ela deve ser compreensível em contexto, distinguível sem apenas cor, acessível por teclado e visualmente focada. Informações essenciais não podem existir apenas na tooltip.

Se uma tooltip for implementada, associe-a à âncora usando aria-describedby enquanto estiver visível. Abra-a tanto no foco do teclado quanto no hover do ponteiro, mantenha-a aberta enquanto o ponteiro se mover sobre a tooltip e permita que a tecla Escape a dispense sem mover o foco. Não coloque controles focáveis dentro de uma tooltip. Não dependa do atributo HTML title como interface de definição: seu tempo, apresentação, suporte a toque e exposição para tecnologia assistiva são inconsistentes. Um title pode ser suplementar, mas não é o nome acessível, descrição ou definição canônica.

O link deve navegar quando os scripts falharem. Em dispositivos de toque, prefira navegação direta em vez de imitação de hover. Se o aprimoramento não puder atender a esses requisitos, envie o link simples.

Regras de redação

Vincule o termo exato ou sua forma completa inequívoca. Mantenha as âncoras entre uma e oito palavras e abaixo de 80 caracteres. Inclua artigos como “um”, “uma”, “o” ou “a” apenas quando fizerem parte de um nome próprio. Não coloque em negrito toda âncora de glossário; a estilização padrão do link já comunica interatividade, e ênfase empilhada torna a prosa técnica ruidosa.

Use um link de glossário por termo por página por padrão. Um segundo link é aceitável apenas quando conteúdo consumido de forma independente — como um apêndice longo, resposta de FAQ autônoma ou módulo incorporado — perderia a relação. Não defina um número mínimo fixo de links de glossário. Uma página clara com dois termos necessários é melhor do que uma página com dez saídas decorativas.

As definições das tooltips devem ter de 40 a 180 caracteres e no máximo duas frases. Declare o que o termo é, não por que o leitor deve clicar. Use linguagem neutra e declarativa. A prévia deve concordar com a definição atual do destino e deve ser obtida do registro do glossário quando possível, para que as atualizações não divirjam.

Nunca coloque estes itens dentro do link ou da tooltip:

• outro link, botão, controle de formulário ou ícone interativo;
• uma alegação de venda ou chamado para ação;
• uma lista de citações ou nota de fonte;
• uma imagem, vídeo, tabela, bloco de código ou procedimento de várias etapas;
• uma definição que conflite com ou se expanda além da página canônica;
• instruções essenciais para a conclusão da tarefa do leitor.

Revise homônimos manualmente. “Java”, “conversão” ou “agente” podem nomear entidades diferentes. A frase e o destino devem resolver o mesmo significado. Nunca alterne destinos para distribuição de links; canonicidade é o objetivo.

Tipos de post que o utilizam

O postTypes[] no frontmatter identifica os formatos para os quais este elemento é uma parte documentada do sistema de conteúdo. A tabela indica como cada formato aplica o mesmo contrato de primeira menção.

Checklist de QA

• Destino canônico: o caminho é a única página de glossário que possui a definição; não é um URL de pesquisa, tag, produto ou artigo relacionado.
• Destino existe: o arquivo de conteúdo existe agora ou o caminho aparece no registro canônico aprovado para a mesma versão.
• Significado corresponde: a âncora e o destino referem-se ao mesmo sentido do termo, incluindo siglas ambíguas e homônimos.
• Primeira menção significativa: o link aparece em prosa antes de usos posteriores, não em um cabeçalho ou exemplo de código apenas porque aquela ocorrência veio primeiro na ordem do código-fonte.
• Âncora exata: as palavras vinculadas nomeiam o termo ou sua forma completa inequívoca; não há “clique aqui” ou substituto vago.
• Frase local funciona: o leitor pode entender a frase sem abrir o destino ou acionar a tooltip.
• Padrão de um por termo: ocorrências repetidas permanecem sem link, a menos que um contexto de leitura independente documentado justifique outro link.
• Sem cluster de links: a frase e o parágrafo permanecem legíveis; termos desconhecidos em excesso são reescritos em vez de cobertos com links.
• Paridade da tooltip: qualquer prévia concorda com a definição canônica e fica entre 40 e 180 caracteres.
• Aprimoramento progressivo: a âncora ainda funciona quando scripts, hover ou estilização da tooltip estão indisponíveis.
• Comportamento do teclado: o foco é visível; a tooltip aparece ao focar, pode ser descartada com Escape e não contém controles focáveis.
• Comportamento de toque: o link tem um tamanho de alvo normal e não requer hover ou interação inexplicável de dois toques.
• Moderação de dados estruturados: nenhuma relação de esquema não suportada ou tipo de elemento inventado é emitida.
• Saída portátil: Markdown, Hugo e WordPress preservam o mesmo termo e href canônico mesmo que os metadados da tooltip sejam descartados.
• Status das capturas de tela: os comentários de captura permanecem como instruções não renderizadas até que os ativos nomeados existam; nenhuma imagem inexistente é referenciada.

FAQ

O template da academia renderiza as perguntas do frontmatter revisadas, cobrindo elegibilidade, primeira menção, escopo da tooltip, consistência canônica e limites de links.