Glossary Term Links and Tooltips: Writing Rules

A glossary term link connects a term at its first meaningful mention to the one page that owns its complete definition. The link helps a reader resolve unfamiliar language without interrupting the article, and it gives crawlers a consistent relationship between the term and its canonical entity page.

A canonical URL is the preferred version of a page when several URLs contain the same or substantially similar content.

That sentence is the live element. The anchor is the exact term, the destination is its canonical glossary entry, and the surrounding sentence remains understandable without opening the link. On systems that support it, the same link may expose a short definition tooltip on hover or keyboard focus. The linked page—not the tooltip—remains the source of truth.

Why this element matters

Readers do not arrive with the same vocabulary. A specialist may recognize “canonical URL” immediately, while a buyer or new team member may need a definition. Explaining every term in parentheses slows expert-facing prose; explaining none excludes newcomers. A glossary term link creates a quiet escape hatch: continue if the term is familiar, or open its definition if it is not.

The first-mention rule matters because uncertainty compounds. If a reader misunderstands a term in paragraph two, every later claim built on that term is harder to evaluate. Linking the first meaningful occurrence resolves the uncertainty before it spreads. The rule does not mean “link the first string match.” A term in a title, navigation label, code sample, or teaser may not yet carry the meaning used in the explanation.

Machine extractability is the ability of software to preserve a relationship after presentation is removed. A descriptive anchor and stable destination create an explicit edge: this page uses the concept, and that glossary page defines it. Consistent edges reinforce which URL owns the definition. They do not create a formal knowledge graph or guarantee visibility, but they reduce ambiguity a crawler would otherwise resolve from proximity alone.

Over-linking reverses those benefits. When every repeated term is linked, the page stops signaling priority. Readers face a field of competing exits, assistive-technology users hear the same destination repeatedly, and machines receive many redundant edges rather than a small set of deliberate relationships. One canonical link at the first meaningful mention is therefore the default, not a minimum to repeat in every section.

When to use it

Use the element when all three conditions are true:

1. The term has a canonical glossary page, rather than several near-duplicate definitions.
2. Understanding the term materially helps the reader understand the current page.
3. The first meaningful use can carry a descriptive anchor without distorting the sentence.

Strong candidates include specialist terminology, acronyms on their first expanded use, named standards, metrics, and words whose domain meaning differs from everyday use. A tooltip can preview one short definition; the full glossary page handles boundaries, examples, sources, and related terms.

Near-miss cases are where the element is most often misused:

• Ordinary vocabulary: do not link a familiar word merely because a glossary entry exists.
• Incidental mentions: if the article names a concept but does not rely on it, a link creates an unnecessary exit.
• Repeated mentions: after the first linked use, leave the term as text unless a long, multi-part page creates a genuinely independent reading context.
• Ambiguous anchor text: “this approach,” “learn more,” and “the metric” do not identify the glossary entity. Link the term itself.
• No canonical destination: do not substitute a search result, tag archive, or loosely related article. Use plain prose until the canonical definition exists.
• Definition already supplied in full: if the glossary adds no useful depth, a second definitional detour may be unnecessary.
• Commercial routing: a glossary link is not a disguised product call to action. Product pages, signup flows, and pricing pages serve different reader intents.

Apply the shared element writing rules before improvising. Their precedence rule requires authors to select an element by purpose. If the purpose is to connect a named term to its canonical definition, use this typed relationship rather than a generic inline link styled to look similar.

Ready to Monitor Your AI Visibility?

Track how AI chatbots mention your brand across ChatGPT, Perplexity, and other platforms.

Get Started Contact

Where to place it

Place the link on the first meaningful prose mention: the first sentence using the concept in the destination’s sense. If the term first appears in the title or an H2, link its first use in the following paragraph. Headings should remain stable section labels rather than large navigation targets.

For an acronym, write the full term followed by the abbreviation and link the full term: retrieval-augmented generation (RAG). Later occurrences may use RAG without a link.

Do not place a glossary term link:

• inside another link, button, or clickable card;
• beside a second link on the same anchor text;
• in code, a URL, an email address, or user-entered literal text;
• in a heading solely to satisfy the first-mention rule;
• in every row of a table when one linked definition in the introduction can establish the term;
• immediately beside a citation marker if the two targets become visually or operationally indistinguishable;
• inside a tooltip trigger that is separate from the actual link.

If a sentence contains several unfamiliar terms, link only the terms needed to understand that sentence. Three or more glossary links in one sentence are a warning that the prose assumes too much vocabulary. Rewrite the sentence, define one concept in place, or split the explanation before adding more exits.

Anatomy

The labelled specimen has six regions:

1. Term anchor: the visible term or complete expanded name, without “learn more.”
2. Canonical destination: one stable glossary URL that owns the definition.
3. Context sentence: enough prose to understand why the term appears, even if the link is not opened.
4. Link styling: the site’s standard inline-link treatment; color is not the only cue.
5. Focus indicator: a visible keyboard state that is not clipped by the paragraph or tooltip.
6. Optional tooltip: a brief preview tied to the link itself, never a separate icon-only control.

Presentation may change without changing the anchor, destination, or first-mention behavior.

Stay Updated on AI Visibility Trends

Get the latest insights on AI mentions, brand monitoring, and optimization strategies.

Email address

Subscribe

Design examples

Every variant preserves the same semantic link.

Default inline link: the required baseline. It works with JavaScript disabled, in reader mode, in print annotations, and on devices without hover.

Definition tooltip on focus or hover: an enhancement for dense educational content. The preview is one or two sentences and never contains links, buttons, citations, or formatting controls.

Mobile and touch: the first tap follows the link unless the product has an established, accessible disclosure pattern. Do not make users discover that one tap opens a preview and a second tap navigates unless that interaction is consistent across the site and clearly communicated.

Dark background: link, focus ring, tooltip text, and tooltip boundary retain clear contrast. Do not remove the underline merely because the accent color is bright.

Parameters

The canonical URL and visible anchor are content decisions. Tooltip behavior belongs to the renderer. Separating those sources prevents an optional interface feature from changing the meaning of the link.

Never infer href from term: homonyms can share spelling while requiring different destinations. Pull a tooltip from the glossary record only when its short definition is reviewed for use outside the page.

Syntax and code examples

All three formats preserve a normal link as the core. The named fields are a portable contract; a platform may render them with a native block, plugin, or preprocessing step.

Portable Markdown directive

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.

If the publishing pipeline does not support inline directives, use ordinary Markdown and omit the tooltip:

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.

This notation specifies the required mapping; it does not require authors to introduce a new shortcode into a project that already handles glossary links through Markdown rendering or content preprocessing. The rendered fallback must always be an ordinary <a href> element.

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

Exported content must retain the anchor and href even when tooltip metadata is unavailable.

Examples

Good

Select one canonical URL for substantially similar pages so indexing signals point to the preferred version.

In the rendered article, “canonical URL” links to /glossary/canonical-url/ on this first meaningful use. The anchor names the entity exactly, the sentence gives enough local context to continue reading, and later occurrences remain plain text. A reader can choose whether the full definition is necessary.

Bad

Select one preferred page for similar pages. Your canonical URL should then reference the canonical URL in every section.

This fails twice. “Preferred page” is related wording but not the exact term the destination defines, so the relationship is less explicit. Repeating the canonical URL link in every section adds exits without adding meaning. The correct repair is to link “canonical URL” once at its first meaningful use and leave later uses unlinked.

Another bad pattern is an information icon after an unlinked term. The icon hides the destination from readers scanning link text, creates a small touch target, and can separate the tooltip from the navigable glossary relationship.

Schema markup and accessibility

A glossary term link needs no standalone Schema.org type. It remains a link inside the enclosing Article, TechArticle, or WebPage. Do not manufacture DefinedTerm, mentions, or about markup for every inline link; add such relationships only through a consistent page-level data model justified by visible content.

Accessibility starts with a real anchor. It must be understandable in context, distinguishable without color alone, keyboard reachable, and visibly focused. Essential information cannot exist only in the tooltip.

If a tooltip is implemented, associate it with the anchor using aria-describedby while it is visible. Open it on keyboard focus as well as pointer hover, keep it open while the pointer moves over the tooltip, and allow Escape to dismiss it without moving focus. Do not place focusable controls inside a tooltip. Do not depend on the HTML title attribute as the definition interface: its timing, presentation, touch support, and assistive-technology exposure are inconsistent. A title may be supplementary, but it is not the accessible name, description, or canonical definition.

The link must navigate when scripts fail. On touch devices, favor direct navigation over hover imitation. If the enhancement cannot meet these requirements, ship the plain link.

Writing rules

Link the exact term or its unambiguous full form. Keep anchors to one to eight words and under 80 characters. Include articles such as “a” or “the” only when they are part of a proper name. Do not bold every glossary anchor; standard link styling already communicates interactivity, and stacked emphasis makes technical prose noisy.

Use one glossary link per term per page by default. A second link is acceptable only when independently consumed content—such as a long appendix, standalone FAQ answer, or embedded module—would otherwise lose the relationship. Do not set a fixed minimum number of glossary links. A clear page with two necessary terms is better than a page with ten decorative exits.

Tooltip definitions should be 40–180 characters and no more than two sentences. State what the term is, not why the reader should click. Use neutral, declarative language. The preview must agree with the destination’s current definition and should be sourced from the glossary record when possible so updates do not diverge.

Never put these inside the link or tooltip:

• another link, button, form control, or interactive icon;
• a sales claim or call to action;
• a citation list or source note;
• an image, video, table, code block, or multi-step procedure;
• a definition that conflicts with or expands beyond the canonical page;
• instructions that are essential to completing the reader’s task.

Review homonyms manually. “Java,” “conversion,” or “agent” can name different entities. The sentence and destination must resolve the same meaning. Never rotate destinations for link distribution; canonicality is the point.

Post types that use it

The postTypes[] frontmatter identifies the formats for which this element is a documented part of the content system. The table states how each format applies the same first-mention contract.

QA checklist

• Canonical destination: the path is the one glossary page that owns the definition; it is not a search, tag, product, or related-article URL.
• Destination exists: the content file exists now or the path appears in the approved canonical registry for the same release.
• Meaning matches: the anchor and destination refer to the same sense of the term, including ambiguous acronyms and homonyms.
• First meaningful mention: the link appears in prose before later uses, not in a heading or code sample merely because that occurrence came first in source order.
• Exact anchor: the linked words name the term or its full unambiguous form; there is no “click here” or vague substitute.
• Local sentence works: a reader can understand the sentence without opening the destination or triggering the tooltip.
• One-per-term default: repeated occurrences remain unlinked unless a documented independent-reading context justifies another link.
• No link cluster: the sentence and paragraph remain readable; excessive unfamiliar terms are rewritten rather than covered with links.
• Tooltip parity: any preview agrees with the canonical definition and stays within 40–180 characters.
• Progressive enhancement: the anchor still works when scripts, hover, or tooltip styling are unavailable.
• Keyboard behavior: focus is visible; the tooltip appears on focus, can be dismissed with Escape, and contains no focusable controls.
• Touch behavior: the link has a normal target size and does not require hover or an unexplained two-tap interaction.
• Structured-data restraint: no unsupported schema relationship or invented element type is emitted.
• Portable output: Markdown, Hugo, and WordPress preserve the same term and canonical href even if tooltip metadata is dropped.
• Screenshot status: capture comments remain non-rendering instructions until the named assets exist; no nonexistent image is referenced.

FAQ

The academy template renders the reviewed frontmatter questions covering eligibility, first mention, tooltip scope, canonical consistency, and link limits.