Enlaces a términos del glosario y tooltips: Reglas de redacción

Un enlace a un término del glosario conecta un término en su primera mención significativa con la única página que posee su definición completa. El enlace ayuda al lector a resolver un lenguaje desconocido sin interrumpir el artículo, y proporciona a los rastreadores una relación coherente entre el término y su página de entidad canónica.

Una URL canónica es la versión preferida de una página cuando varias URL contienen el mismo contenido o contenido sustancialmente similar.

Esa oración es el elemento en funcionamiento. El ancla es el término exacto, el destino es su entrada canónica del glosario, y la oración circundante sigue siendo comprensible sin abrir el enlace. En los sistemas que lo admiten, el mismo enlace puede mostrar un tooltip con una definición breve al pasar el ratón o al recibir el foco del teclado. La página enlazada —no el tooltip— sigue siendo la fuente de verdad.

Por qué es importante este elemento

Los lectores no llegan con el mismo vocabulario. Un especialista puede reconocer «URL canónica» de inmediato, mientras que un comprador o un miembro nuevo del equipo puede necesitar una definición. Explicar cada término entre paréntesis ralentiza la prosa para expertos; no explicar ninguno excluye a los recién llegados. Un enlace a un término del glosario crea una vía de escape silenciosa: continúa si el término te resulta familiar, o abre su definición si no lo es.

La regla de la primera mención es importante porque la incertidumbre se acumula. Si un lector malinterpreta un término en el segundo párrafo, cada afirmación posterior basada en ese término será más difícil de evaluar. Enlazar la primera aparición significativa resuelve la incertidumbre antes de que se propague. La regla no significa «enlazar la primera coincidencia de cadena». Un término en un título, etiqueta de navegación, ejemplo de código o avance puede no tener aún el significado que se usa en la explicación.

La extraíble por máquina es la capacidad del software de preservar una relación una vez eliminada la presentación. Un ancla descriptiva y un destino estable crean un borde explícito: esta página usa el concepto, y esa página del glosario lo define. Los bordes coherentes refuerzan qué URL posee la definición. No crean un grafo de conocimiento formal ni garantizan visibilidad, pero reducen la ambigüedad que un rastreador resolvería únicamente por proximidad.

El exceso de enlaces revierte esos beneficios. Cuando cada término repetido está enlazado, la página deja de señalar prioridades. Los lectores se enfrentan a un campo de salidas competidoras, los usuarios de tecnología de asistencia escuchan el mismo destino repetidamente y las máquinas reciben muchos bordes redundantes en lugar de un pequeño conjunto de relaciones deliberadas. Por tanto, un enlace canónico en la primera mención significativa es el valor predeterminado, no un mínimo que repetir en cada sección.

Cuándo usarlo

Usa el elemento cuando se cumplan las tres condiciones:

1. El término tiene una página canónica de glosario, no varias definiciones casi duplicadas.
2. Entender el término ayuda materialmente al lector a comprender la página actual.
3. El primer uso significativo puede llevar un ancla descriptiva sin distorsionar la oración.

Entre los candidatos sólidos se incluyen terminología especializada, acrónimos en su primera aparición expandida, normas con nombre, métricas y palabras cuyo significado en el dominio difiere del uso cotidiano. Un tooltip puede previsualizar una definición breve; la página completa del glosario maneja los límites, ejemplos, fuentes y términos relacionados.

Los casos límite son donde el elemento se usa incorrectamente con más frecuencia:

• Vocabulario ordinario: no enlaces una palabra familiar solo porque exista una entrada en el glosario.
• Menciones incidentales: si el artículo nombra un concepto pero no depende de él, un enlace crea una salida innecesaria.
• Menciones repetidas: tras el primer uso enlazado, deja el término como texto a menos que una página larga dividida en partes cree un contexto de lectura genuinamente independiente.
• Texto de anclaje ambiguo: «este enfoque», «más información» y «la métrica» no identifican la entidad del glosario. Enlaza el término en sí mismo.
• Sin destino canónico: no sustituyas con un resultado de búsqueda, un archivo de etiquetas o un artículo vagamente relacionado. Usa prosa simple hasta que exista la definición canónica.
• Definición ya proporcionada completa: si el glosario no añade profundidad útil, un segundo desvío definicional puede ser innecesario.
• Redireccionamiento comercial: un enlace al glosario no es una llamada a la acción encubierta para un producto. Las páginas de producto, los flujos de registro y las páginas de precios atienden intenciones de lectura diferentes.

Aplica las reglas de redacción de elementos compartidas antes de improvisar. Su regla de precedencia exige que los autores seleccionen un elemento según su propósito. Si el propósito es conectar un término con nombre a su definición canónica, usa esta relación tipificada en lugar de un enlace en línea genérico con un estilo similar.

Dónde colocarlo

Coloca el enlace en la primera mención significativa en prosa: la primera oración que use el concepto en el sentido del destino. Si el término aparece primero en el título o en un H2, enlaza su primer uso en el párrafo siguiente. Los encabezados deben seguir siendo etiquetas de sección estables en lugar de grandes objetivos de navegación.

Para un acrónimo, escribe el término completo seguido de la abreviatura y enlaza el término completo: retrieval-augmented generation (RAG). Las apariciones posteriores pueden usar RAG sin enlace.

No coloques un enlace a un término del glosario:

• dentro de otro enlace, botón o tarjeta cliqueable;
• junto a un segundo enlace sobre el mismo texto de anclaje;
• en código, una URL, una dirección de correo electrónico o texto literal introducido por el usuario;
• en un encabezado únicamente para cumplir la regla de la primera mención;
• en cada fila de una tabla cuando una definición enlazada en la introducción puede establecer el término;
• inmediatamente junto a un marcador de cita si los dos objetivos se vuelven visual o funcionalmente indistinguibles;
• dentro de un activador de tooltip que sea independiente del enlace real.

Si una oración contiene varios términos desconocidos, enlaza solo los términos necesarios para entender esa oración. Tres o más enlaces al glosario en una sola oración son una advertencia de que la prosa asume demasiado vocabulario. Reescribe la oración, define un concepto en su lugar o divide la explicación antes de añadir más salidas.

Anatomía

El espécimen etiquetado tiene seis regiones:

1. Ancla del término: el término visible o el nombre expandido completo, sin «más información».
2. Destino canónico: una URL de glosario estable que posee la definición.
3. Oración de contexto: suficiente prosa para entender por qué aparece el término, incluso si no se abre el enlace.
4. Estilo del enlace: el tratamiento estándar de enlace en línea del sitio; el color no es la única señal.
5. Indicador de foco: un estado de teclado visible que no queda recortado por el párrafo o el tooltip.
6. Tooltip opcional: una vista previa breve vinculada al propio enlace, nunca un control independiente solo con icono.

La presentación puede cambiar sin alterar el ancla, el destino o el comportamiento de primera mención.

Ejemplos de diseño

Cada variante preserva el mismo enlace semántico.

Enlace en línea predeterminado: la línea base requerida. Funciona con JavaScript desactivado, en modo lectura, en anotaciones impresas y en dispositivos sin capacidad de hover.

Tooltip de definición al recibir foco o al pasar el ratón: una mejora para contenido educativo denso. La vista previa es de una o dos oraciones y nunca contiene enlaces, botones, citas ni controles de formato.

Móvil y táctil: el primer toque sigue el enlace a menos que el producto tenga un patrón de divulgación establecido y accesible. No hagas que los usuarios descubran que un toque abre una vista previa y un segundo toque navega, a menos que esa interacción sea coherente en todo el sitio y esté claramente comunicada.

Fondo oscuro: el enlace, el anillo de foco, el texto del tooltip y el borde del tooltip mantienen un contraste claro. No elimines el subrayado solo porque el color de acento sea brillante.

Parámetros

La URL canónica y el ancla visible son decisiones de contenido. El comportamiento del tooltip pertenece al motor de renderizado. Separar esas fuentes evita que una función de interfaz opcional cambie el significado del enlace.

Nunca infieras href a partir de term: los homónimos pueden compartir ortografía pero requerir destinos diferentes. Obtén un tooltip del registro del glosario solo cuando su definición breve haya sido revisada para su uso fuera de la página.

Sintaxis y ejemplos de código

Los tres formatos preservan un enlace normal como núcleo. Los campos con nombre son un contrato portátil; una plataforma puede renderizarlos con un bloque nativo, un plugin o un paso de preprocesamiento.

Directiva 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.

Si el pipeline de publicación no admite directivas en línea, usa Markdown ordinario y omite el tooltip:

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

Shortcode de 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 notación especifica el mapeo requerido; no exige que los autores introduzcan un nuevo shortcode en un proyecto que ya maneje enlaces al glosario mediante renderizado Markdown o preprocesamiento de contenido. La alternativa renderizada debe ser siempre un elemento <a href> ordinario.

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 -->

El contenido exportado debe conservar el ancla y el href incluso cuando los metadatos del tooltip no estén disponibles.

Ejemplos

Correcto

Selecciona una URL canónica para páginas sustancialmente similares, de modo que las señales de indexación apunten a la versión preferida.

En el artículo renderizado, «URL canónica» enlaza a /glossary/canonical-url/ en este primer uso significativo. El ancla nombra la entidad exactamente, la oración proporciona suficiente contexto local para seguir leyendo, y las apariciones posteriores quedan como texto plano. El lector puede decidir si la definición completa es necesaria.

Incorrecto

Selecciona una página preferida para páginas similares. Tu URL canónica debería hacer referencia a la URL canónica en cada sección.

Esto falla dos veces. «Página preferida» es una redacción relacionada pero no el término exacto que define el destino, por lo que la relación es menos explícita. Repetir el enlace de URL canónica en cada sección añade salidas sin añadir significado. La solución correcta es enlazar «URL canónica» una vez en su primer uso significativo y dejar los usos posteriores sin enlazar.

Otro patrón incorrecto es un icono de información después de un término sin enlazar. El icono oculta el destino a los lectores que escanean el texto del enlace, crea un objetivo táctil pequeño y puede separar el tooltip de la relación navegable del glosario.

Marcado Schema y accesibilidad

Un enlace a un término del glosario no necesita un tipo Schema.org independiente. Sigue siendo un enlace dentro del Article, TechArticle o WebPage que lo contiene. No generes marcado DefinedTerm, mentions o about para cada enlace en línea; añade dichas relaciones solo a través de un modelo de datos coherente a nivel de página que esté justificado por el contenido visible.

La accesibilidad comienza con un ancla real. Debe ser comprensible en contexto, distinguible sin usar solo el color, alcanzable mediante teclado y visible al recibir el foco. La información esencial no puede existir únicamente en el tooltip.

Si se implementa un tooltip, asócialo con el ancla usando aria-describedby mientras esté visible. Ábrelo al recibir el foco del teclado así como al pasar el ratón por encima, mantenlo abierto mientras el puntero se mueva sobre el tooltip y permite que Escape lo cierre sin mover el foco. No coloques controles enfocables dentro de un tooltip. No dependas del atributo HTML title como interfaz de definición: su temporización, presentación, soporte táctil y exposición a la tecnología de asistencia son inconsistentes. Un title puede ser suplementario, pero no es el nombre accesible, la descripción ni la definición canónica.

El enlace debe navegar cuando los scripts fallen. En dispositivos táctiles, favorece la navegación directa sobre la imitación de hover. Si la mejora no puede cumplir estos requisitos, envía el enlace simple.

Reglas de redacción

Enlaza el término exacto o su forma completa inequívoca. Mantén los anclas de una a ocho palabras y menos de 80 caracteres. Incluye artículos como «un», «una», «el» o «la» solo cuando formen parte de un nombre propio. No pongas en negrita cada ancla del glosario; el estilo de enlace estándar ya comunica interactividad, y el énfasis apilado hace que la prosa técnica sea ruidosa.

Usa un enlace al glosario por término y página por defecto. Un segundo enlace solo es aceptable cuando contenido consumido de forma independiente —como un apéndice extenso, una respuesta de FAQ independiente o un módulo incrustado— perdería la relación en caso contrario. No establezcas un número mínimo fijo de enlaces al glosario. Una página clara con dos términos necesarios es mejor que una página con diez salidas decorativas.

Las definiciones del tooltip deben tener entre 40 y 180 caracteres y no más de dos oraciones. Indica qué es el término, no por qué el lector debería hacer clic. Usa un lenguaje neutro y declarativo. La vista previa debe coincidir con la definición actual del destino y, cuando sea posible, debe obtenerse del registro del glosario para que las actualizaciones no diverjan.

Nunca pongas esto dentro del enlace o del tooltip:

• otro enlace, botón, control de formulario o icono interactivo;
• una afirmación comercial o llamada a la acción;
• una lista de citas o nota de fuente;
• una imagen, video, tabla, bloque de código o procedimiento de varios pasos;
• una definición que entre en conflicto o se extienda más allá de la página canónica;
• instrucciones que sean esenciales para completar la tarea del lector.

Revisa los homónimos manualmente. «Java», «conversión» o «agente» pueden nombrar entidades diferentes. La oración y el destino deben resolver el mismo significado. Nunca rote los destinos para distribuir enlaces; la canonicidad es el objetivo.

Tipos de publicación que lo usan

El frontmatter postTypes[] identifica los formatos para los que este elemento es una parte documentada del sistema de contenido. La tabla indica cómo cada formato aplica el mismo contrato de primera mención.

Lista de verificación de QA

• Destino canónico: la ruta es la única página del glosario que posee la definición; no es una URL de búsqueda, etiqueta, producto o artículo relacionado.
• El destino existe: el archivo de contenido existe ahora o la ruta aparece en el registro canónico aprobado para la misma versión.
• El significado coincide: el ancla y el destino se refieren al mismo sentido del término, incluidos acrónimos ambiguos y homónimos.
• Primera mención significativa: el enlace aparece en prosa antes de usos posteriores, no en un encabezado o ejemplo de código solo porque esa aparición fue primera en el orden del código fuente.
• Ancla exacta: las palabras enlazadas nombran el término o su forma completa inequívoca; no hay «haz clic aquí» ni sustituto vago.
• La oración local funciona: un lector puede entender la oración sin abrir el destino ni activar el tooltip.
• Uno por término predeterminado: las apariciones repetidas quedan sin enlazar a menos que un contexto de lectura independiente documentado justifique otro enlace.
• Sin agrupación de enlaces: la oración y el párrafo siguen siendo legibles; los términos desconocidos excesivos se reescriben en lugar de cubrirse con enlaces.
• Paridad del tooltip: cualquier vista previa coincide con la definición canónica y se mantiene entre 40 y 180 caracteres.
• Mejora progresiva: el ancla sigue funcionando cuando los scripts, el hover o el estilo del tooltip no están disponibles.
• Comportamiento de teclado: el foco es visible; el tooltip aparece al recibir foco, se puede descartar con Escape y no contiene controles enfocables.
• Comportamiento táctil: el enlace tiene un tamaño de objetivo normal y no requiere hover ni una interacción de dos toques no explicada.
• Restricción de datos estructurados: no se emite ninguna relación de esquema no admitida ni tipo de elemento inventado.
• Salida portátil: Markdown, Hugo y WordPress preservan el mismo término y href canónico incluso si se eliminan los metadatos del tooltip.
• Estado de capturas de pantalla: los comentarios de captura siguen siendo instrucciones no renderizadas hasta que existan los archivos nombrados; no se referencia ninguna imagen inexistente.

FAQ

La plantilla de la academia renderiza las preguntas del frontmatter revisadas que cubren elegibilidad, primera mención, alcance del tooltip, consistencia canónica y límites de enlaces.