Woordenlijsttermlinks en tooltips: Schrijfregels

Een woordenlijsttermlink verbindt een term bij de eerste betekenisvolle vermelding met de ene pagina die de volledige definitie ervan beheert. De link helpt een lezer onbekende taal te begrijpen zonder het artikel te onderbreken, en geeft crawlers een consistente relatie tussen de term en de canonieke entiteitspagina.

Een canonieke URL is de voorkeursversie van een pagina wanneer meerdere URL’s dezelfde of grotendeels dezelfde inhoud bevatten.

Die zin is het live element. Het anker is de exacte term, de bestemming is de canonieke woordenlijstvermelding en de omringende zin blijft begrijpelijk zonder de link te openen. Op systemen die dit ondersteunen, kan dezelfde link bij hover of toetsenbordfocus een korte definitietooltip tonen. De gelinkte pagina — niet de tooltip — blijft de bron van waarheid.

Waarom dit element belangrijk is

Lezers komen niet met dezelfde woordenschat aan. Een specialist herkent ‘canonieke URL’ misschien meteen, terwijl een koper of nieuw teamlid mogelijk een definitie nodig heeft. Elke term tussen haakjes uitleggen vertraagt expertgericht proza; niets uitleggen sluit nieuwkomers uit. Een woordenlijsttermlink creëert een stille ontsnappingsluik: ga verder als de term bekend is, of open de definitie als dat niet het geval is.

De regel van de eerste vermelding is belangrijk omdat onzekerheid zich opstapelt. Als een lezer een term in alinea twee verkeerd begrijpt, wordt elk later argument dat op die term is gebouwd moeilijker te beoordelen. Het linken van het eerste betekenisvolle voorkomen lost de onzekerheid op voordat deze zich verspreidt. De regel betekent niet ’link de eerste stringovereenkomst’. Een term in een titel, navigatielabel, codevoorbeeld of teaser heeft mogelijk nog niet de betekenis die in de uitleg wordt gebruikt.

Machine-extraheerbaarheid is het vermogen van software om een relatie te behouden nadat de presentatie is verwijderd. Een beschrijvend anker en een stabiele bestemming creëren een expliciete verbinding: deze pagina gebruikt het concept en die woordenlijstpagina definieert het. Consistente verbindingen versterken welke URL de definitie beheert. Ze creëren geen formele kennisgraaf en garanderen geen zichtbaarheid, maar ze verminderen dubbelzinnigheid die een crawler anders alleen uit nabijheid zou moeten afleiden.

Overmatig linken keert die voordelen om. Wanneer elke herhaalde term wordt gelinkt, stopt de pagina met het aangeven van prioriteit. Lezers worden geconfronteerd met een veld van concurrerende uitgangen, gebruikers van ondersteunende technologie horen dezelfde bestemming herhaaldelijk en machines krijgen veel redundante verbindingen in plaats van een kleine set weloverwogen relaties. Eén canonieke link bij de eerste betekenisvolle vermelding is daarom de standaard, niet een minimum dat in elke sectie moet worden herhaald.

Wanneer het te gebruiken

Gebruik het element wanneer aan alle drie voorwaarden is voldaan:

1. De term heeft een canonieke woordenlijstpagina, in plaats van meerdere bijna-identieke definities.
2. Het begrijpen van de term helpt de lezer wezenlijk de huidige pagina te begrijpen.
3. Het eerste betekenisvolle gebruik kan een beschrijvend anker dragen zonder de zin te vervormen.

Sterke kandidaten zijn specialistische terminologie, acroniemen bij het eerste uitgeschreven gebruik, benoemde standaarden, meetgegevens en woorden waarvan de domeinbetekenis verschilt van het dagelijks gebruik. Een tooltip kan een korte definitie voorvertonen; de volledige woordenlijstpagina behandelt grenzen, voorbeelden, bronnen en gerelateerde termen.

Bijna-goed-gevallen zijn waar het element het vaakst verkeerd wordt gebruikt:

• Gewone woordenschat: link geen bekend woord alleen omdat er een woordenlijstvermelding bestaat.
• Terloopse vermeldingen: als het artikel een concept noemt maar er niet op vertrouwt, creëert een link een onnodige uitgang.
• Herhaalde vermeldingen: na het eerste gelinkte gebruik blijft de term tekst, tenzij een lange, meerledige pagina een werkelijk onafhankelijke leescontext creëert.
• Dubbelzinnige ankertekst: ‘deze aanpak’, ’lees meer’ en ‘de metriek’ identificeren de woordenlijstentiteit niet. Link de term zelf.
• Geen canonieke bestemming: vervang geen zoekresultaat, tagarchief of losjes gerelateerd artikel. Gebruik gewoon proza totdat de canonieke definitie bestaat.
• Definitie al volledig gegeven: als de woordenlijst geen nuttige verdieping toevoegt, is een tweede definitieve omweg mogelijk onnodig.
• Commerciële routering: een woordenlijstlink is geen vermomde product-call-to-action. Productpagina’s, aanmeldstromen en prijspagina’s dienen andere lezersintenties.

Pas de gedeelde elementschrijfregels toe voordat je improviseert. Hun voorrangsregel vereist dat auteurs een element op basis van doel selecteren. Als het doel is om een benoemde term te verbinden met de canonieke definitie, gebruik dan deze getypeerde relatie in plaats van een generieke inline-link die er vergelijkbaar uitziet.

Waar het te plaatsen

Plaats de link bij de eerste betekenisvolle prozavermelding: de eerste zin die het concept gebruikt in de betekenis van de bestemming. Als de term voor het eerst verschijnt in de titel of een H2, link dan het eerste gebruik in de volgende alinea. Koppen moeten stabiele sectielabels blijven in plaats van grote navigatiedoelen.

Voor een acroniem: schrijf de volledige term gevolgd door de afkorting en link de volledige term: retrieval-augmented generation (RAG). Latere vermeldingen kunnen RAG gebruiken zonder link.

Plaats geen woordenlijsttermlink:

• binnen een andere link, knop of aanklikbare kaart;
• naast een tweede link met dezelfde ankertekst;
• in code, een URL, een e-mailadres of letterlijke gebruikerstekst;
• in een kop uitsluitend om aan de regel van de eerste vermelding te voldoen;
• in elke rij van een tabel wanneer één gelinkte definitie in de inleiding de term kan vaststellen;
• direct naast een citatiemarker als de twee doelen visueel of operationeel niet van elkaar te onderscheiden zijn;
• binnen een tooltip-trigger die losstaat van de daadwerkelijke link.

Als een zin verschillende onbekende termen bevat, link dan alleen de termen die nodig zijn om die zin te begrijpen. Drie of meer woordenlijstlinks in één zin zijn een waarschuwing dat het proza te veel woordenschat veronderstelt. Herschrijf de zin, definieer één concept ter plaatse of splits de uitleg op voordat je meer uitgangen toevoegt.

Anatomie

Het gelabelde specimen heeft zes gebieden:

1. Termanker: de zichtbare term of volledige uitgeschreven naam, zonder ’lees meer’.
2. Canonieke bestemming: één stabiele woordenlijst-URL die de definitie beheert.
3. Contextzin: voldoende proza om te begrijpen waarom de term verschijnt, zelfs als de link niet wordt geopend.
4. Linkopmaak: de standaard inline-linkbehandeling van de site; kleur is niet de enige aanwijzing.
5. Focusindicator: een zichtbare toetsenbordstatus die niet wordt afgekapt door de alinea of tooltip.
6. Optionele tooltip: een korte voorvertoning gekoppeld aan de link zelf, nooit een aparte alleen-pictogram bediening.

Presentatie kan veranderen zonder het anker, de bestemming of het gedrag van de eerste vermelding te veranderen.

Ontwerpvoorbeelden

Elke variant behoudt dezelfde semantische link.

Standaard inline-link: de vereiste basislijn. Het werkt met uitgeschakelde JavaScript, in leesmodus, in printannotaties en op apparaten zonder hover.

Definitietooltip bij focus of hover: een verbetering voor dichte educatieve inhoud. De voorvertoning is één of twee zinnen en bevat nooit links, knoppen, citaten of opmaakbedieningen.

Mobiel en aanraking: de eerste tik volgt de link, tenzij het product een gevestigd, toegankelijk onthullingspatroon heeft. Laat gebruikers niet ontdekken dat één tik een voorvertoning opent en een tweede tik navigeert, tenzij die interactie consistent is op de hele site en duidelijk wordt gecommuniceerd.

Donkere achtergrond: link, focusring, tooltiptekst en tooltipgrens behouden duidelijk contrast. Verwijder de onderstreping niet alleen omdat de accentkleur helder is.

Parameters

De canonieke URL en het zichtbare anker zijn inhoudelijke beslissingen. Tooltipgedrag behoort tot de renderer. Het scheiden van die bronnen voorkomt dat een optionele interfacefunctie de betekenis van de link verandert.

Leid href nooit af van term: homoniemen kunnen dezelfde spelling delen maar verschillende bestemmingen vereisen. Haal een tooltip alleen uit het woordenlijstrecord wanneer de korte definitie is beoordeeld voor gebruik buiten de pagina.

Syntax en codevoorbeelden

Alle drie formaten behouden een normale link als kern. De benoemde velden zijn een draagbaar contract; een platform kan ze renderen met een native blok, plugin of voorverwerkingsstap.

Draagbare Markdown-richtlijn

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.

Als de publicatiepijplijn geen inline-richtlijnen ondersteunt, gebruik dan gewone Markdown en laat de tooltip weg:

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

Hugo shortcode

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.

Deze notatie specificeert de vereiste mapping; het vereist niet dat auteurs een nieuwe shortcode introduceren in een project dat al woordenlijstlinks afhandelt via Markdown-rendering of contentvoorverwerking. De gerenderde terugval moet altijd een gewoon <a href>-element zijn.

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

Geëxporteerde inhoud moet het anker en de href behouden, zelfs wanneer tooltip-metadata niet beschikbaar is.

Voorbeelden

Goed

Selecteer één canonieke URL voor grotendeels vergelijkbare pagina’s, zodat indexeringssignalen naar de voorkeursversie wijzen.

In het gerenderde artikel linkt ‘canonieke URL’ naar /glossary/canonical-url/ bij dit eerste betekenisvolle gebruik. Het anker benoemt de entiteit exact, de zin geeft voldoende lokale context om verder te lezen en latere vermeldingen blijven platte tekst. Een lezer kan kiezen of de volledige definitie nodig is.

Fout

Selecteer één voorkeurspagina voor vergelijkbare pagina’s. Uw canonieke URL moet vervolgens naar de canonieke URL verwijzen in elke sectie.

Dit faalt dubbel. ‘Voorkeurspagina’ is verwante bewoording maar niet de exacte term die de bestemming definieert, waardoor de relatie minder expliciet is. Het herhalen van de canonieke URL-link in elke sectie voegt uitgangen toe zonder betekenis toe te voegen. De juiste reparatie is om ‘canonieke URL’ één keer te linken bij het eerste betekenisvolle gebruik en latere vermeldingen ongelinkt te laten.

Een ander fout patroon is een informatiepictogram na een ongelinkte term. Het pictogram verbergt de bestemming voor lezers die linktekst scannen, creëert een klein aanraakdoel en kan de tooltip scheiden van de navigeerbare woordenlijstrelatie.

Schema-markup en toegankelijkheid

Een woordenlijsttermlink heeft geen zelfstandig Schema.org-type nodig. Het blijft een link binnen de omringende Article, TechArticle of WebPage. Verzin geen DefinedTerm-, mentions- of about-markup voor elke inline-link; voeg dergelijke relaties alleen toe via een consistent paginaniveau-gegevensmodel dat wordt gerechtvaardigd door zichtbare inhoud.

Toegankelijkheid begint met een echt anker. Het moet begrijpelijk zijn in context, te onderscheiden zonder alleen kleur, bereikbaar met toetsenbord en zichtbaar gefocust. Essentiële informatie mag niet alleen in de tooltip bestaan.

Als een tooltip is geïmplementeerd, koppel deze dan aan het anker met aria-describedby terwijl deze zichtbaar is. Open deze bij toetsenbordfocus en bij muisaanwijzer-hover, houd deze open terwijl de aanwijzer over de tooltip beweegt en sta toe dat Escape deze sluit zonder de focus te verplaatsen. Plaats geen focusbare bedieningen in een tooltip. Vertrouw niet op het HTML-title-attribuut als definitie-interface: de timing, presentatie, aanraakondersteuning en blootstelling aan ondersteunende technologie zijn inconsistent. Een title kan aanvullend zijn, maar het is niet de toegankelijke naam, beschrijving of canonieke definitie.

De link moet navigeren wanneer scripts falen. Op aanraakapparaten heeft directe navigatie de voorkeur boven hover-nabootsing. Als de verbetering niet aan deze vereisten kan voldoen, lever dan de gewone link.

Schrijfregels

Link de exacte term of de ondubbelzinnige volledige vorm. Houd ankers tussen één en acht woorden en onder de 80 tekens. Neem lidwoorden zoals ’een’ of ‘de’ alleen op wanneer ze deel uitmaken van een eigennaam. Maak niet elk woordenlijstanker vetgedrukt; standaard linkopmaak communiceert al interactiviteit, en gestapelde nadruk maakt technisch proza rommelig.

Gebruik standaard één woordenlijstlink per term per pagina. Een tweede link is alleen acceptabel wanneer onafhankelijk geconsumeerde inhoud — zoals een lange bijlage, zelfstandig FAQ-antwoord of ingebedde module — anders de relatie zou verliezen. Stel geen vast minimumaantal woordenlijstlinks in. Een duidelijke pagina met twee noodzakelijke termen is beter dan een pagina met tien decoratieve uitgangen.

Tooltipdefinities moeten 40–180 tekens zijn en niet meer dan twee zinnen. Vertel wat de term is, niet waarom de lezer moet klikken. Gebruik neutrale, declaratieve taal. De voorvertoning moet overeenkomen met de huidige definitie van de bestemming en moet waar mogelijk uit het woordenlijstrecord worden gehaald, zodat updates niet uiteenlopen.

Plaats nooit het volgende in de link of tooltip:

• een andere link, knop, formulierbediening of interactief pictogram;
• een verkoopclaim of call-to-action;
• een citatielijst of bronvermelding;
• een afbeelding, video, tabel, codeblok of meerstapsprocedure;
• een definitie die in strijd is met of verder gaat dan de canonieke pagina;
• instructies die essentieel zijn voor het voltooien van de taak van de lezer.

Beoordeel homoniemen handmatig. ‘Java’, ‘conversie’ of ‘agent’ kunnen verschillende entiteiten benoemen. De zin en de bestemming moeten dezelfde betekenis oplossen. Wissel nooit van bestemming voor linkdistributie; canonicaliteit is het doel.

Posttypes die het gebruiken

De postTypes[] frontmatter identificeert de formaten waarvoor dit element een gedocumenteerd onderdeel is van het contentsysteem. De tabel geeft aan hoe elk formaat hetzelfde eerste-vermelding-contract toepast.

QA-checklist

• Canonieke bestemming: het pad is de ene woordenlijstpagina die de definitie beheert; het is geen zoek-, tag-, product- of gerelateerd-artikel-URL.
• Bestemming bestaat: het contentbestand bestaat nu of het pad verschijnt in het goedgekeurde canonieke register voor dezelfde release.
• Betekenis komt overeen: het anker en de bestemming verwijzen naar dezelfde betekenis van de term, inclusief dubbelzinnige acroniemen en homoniemen.
• Eerste betekenisvolle vermelding: de link verschijnt in proza vóór later gebruik, niet in een kop of codevoorbeeld alleen omdat dat voorkomen als eerste in de bronvolgorde kwam.
• Exact anker: de gelinkte woorden benoemen de term of de ondubbelzinnige volledige vorm; er is geen ‘klik hier’ of vage vervanging.
• Lokale zin werkt: een lezer kan de zin begrijpen zonder de bestemming te openen of de tooltip te activeren.
• Eén-per-term-standaard: herhaalde vermeldingen blijven ongelinkt, tenzij een gedocumenteerde onafhankelijke leescontext een andere link rechtvaardigt.
• Geen linkcluster: de zin en alfa blijven leesbaar; overmatige onbekende termen worden herschreven in plaats van bedekt met links.
• Tooltip-pariteit: elke voorvertoning komt overeen met de canonieke definitie en blijft binnen 40–180 tekens.
• Progressieve verbetering: het anker werkt nog steeds wanneer scripts, hover of tooltipopmaak niet beschikbaar zijn.
• Toetsenbordgedrag: focus is zichtbaar; de tooltip verschijnt bij focus, kan worden gesloten met Escape en bevat geen focusbare bedieningen.
• Aanraakgedrag: de link heeft een normaal doelgrootte en vereist geen hover of een onverklaarde twee-tik-interactie.
• Gestructureerde-gegevens terughoudendheid: er wordt geen niet-ondersteunde schemarelatie of verzonnen elementtype uitgezonden.
• Draagbare uitvoer: Markdown, Hugo en WordPress behouden dezelfde term en canonieke href, zelfs als tooltip-metadata wordt verwijderd.
• Schermafbeeldingsstatus: opmerkingen blijven niet-renderende instructies totdat de genoemde assets bestaan; er wordt naar geen niet-bestaande afbeelding verwezen.

FAQ

De academysjabloon rendert de beoordeelde frontmatter-vragen over geschiktheid, eerste vermelding, tooltip-reikwijdte, canonieke consistentie en linklimieten.