Glossar-Begriffslinks und Tooltipps: Schreibregeln

Ein Glossar-Begriffslink verbindet einen Begriff bei seiner ersten sinnvollen Erwähnung mit der einen Seite, die seine vollständige Definition bereitstellt. Der Link hilft dem Leser, unbekannte Sprache aufzulösen, ohne den Artikel zu unterbrechen, und gibt Crawlern eine konsistente Beziehung zwischen dem Begriff und seiner kanonischen Entitätsseite.

Eine kanonische URL ist die bevorzugte Version einer Seite, wenn mehrere URLs denselben oder im Wesentlichen ähnlichen Inhalt enthalten.

Dieser Satz ist das lebende Element. Der Anker ist der exakte Begriff, das Ziel ist sein kanonischer Glossareintrag, und der umgebende Satz bleibt auch ohne Öffnen des Links verständlich. In Systemen, die dies unterstützen, kann derselbe Link bei Hover oder Tastaturfokus eine Kurzdefinition als Tooltipp anzeigen. Die verlinkte Seite – nicht der Tooltipp – bleibt die maßgebliche Quelle.

Warum dieses Element wichtig ist

Leser kommen nicht mit demselben Vokabular. Ein Spezialist erkennt „kanonische URL“ sofort, während ein Käufer oder ein neues Teammitglied möglicherweise eine Definition benötigt. Jeden Begriff in Klammern zu erklären, verlangsamt den Text für Experten; nichts zu erklären, schließt Neulinge aus. Ein Glossar-Begriffslink schafft eine leise Notluke: Lesen Sie weiter, wenn der Begriff vertraut ist, oder öffnen Sie seine Definition, wenn nicht.

Die Regel der ersten Erwähnung ist wichtig, weil Unsicherheit sich verstärkt. Wenn ein Leser einen Begriff in Absatz zwei missversteht, wird jede spätere Aussage, die auf diesem Begriff aufbaut, schwerer zu bewerten sein. Die Verlinkung des ersten sinnvollen Vorkommens löst die Unsicherheit auf, bevor sie sich ausbreitet. Die Regel bedeutet nicht „verlinke die erste Zeichenketten-Übereinstimmung“. Ein Begriff in einem Titel, einer Navigationsbeschriftung, einem Codebeispiel oder einem Teaser trägt möglicherweise noch nicht die Bedeutung, die in der Erklärung verwendet wird.

Maschinelle Extrahierbarkeit ist die Fähigkeit von Software, eine Beziehung zu bewahren, nachdem die Darstellung entfernt wurde. Ein beschreibender Anker und ein stabiles Ziel erzeugen eine explizite Kante: Diese Seite verwendet das Konzept, und jene Glossarseite definiert es. Konsistente Kanten verstärken, welche URL die Definition besitzt. Sie schaffen keinen formalen Wissensgraphen und garantieren keine Sichtbarkeit, aber sie reduzieren Mehrdeutigkeiten, die ein Crawler sonst nur aus der Nähe der Begriffe ableiten müsste.

Übermäßige Verlinkung kehrt diese Vorteile um. Wenn jeder wiederholte Begriff verlinkt ist, hört die Seite auf, Prioritäten zu signalisieren. Leser stehen vor einem Feld konkurrierender Ausgänge, Nutzer von assistiven Technologien hören immer wieder dasselbe Ziel, und Maschinen erhalten viele redundante Kanten statt einer kleinen Menge durchdachter Beziehungen. Ein kanonischer Link bei der ersten sinnvollen Erwähnung ist daher der Standard, nicht eine Mindestanzahl, die in jedem Abschnitt wiederholt werden muss.

Wann es verwendet werden soll

Verwenden Sie das Element, wenn alle drei Bedingungen erfüllt sind:

1. Der Begriff hat eine kanonische Glossarseite, nicht mehrere nahezu identische Definitionen.
2. Das Verständnis des Begriffs hilft dem Leser wesentlich, die aktuelle Seite zu verstehen.
3. Die erste sinnvolle Verwendung kann einen beschreibenden Anker tragen, ohne den Satz zu verzerren.

Starke Kandidaten sind Fachterminologie, Akronyme bei ihrer ersten ausgeschriebenen Verwendung, benannte Standards, Kennzahlen und Wörter, deren fachliche Bedeutung von der alltäglichen abweicht. Ein Tooltipp kann eine kurze Definition vorab zeigen; die vollständige Glossarseite behandelt Abgrenzungen, Beispiele, Quellen und verwandte Begriffe.

Beinahe-Fehlerfälle, bei denen das Element am häufigsten falsch verwendet wird:

• Alltägliches Vokabular: Verlinken Sie kein vertrautes Wort, nur weil ein Glossareintrag existiert.
• Beiläufige Erwähnungen: Wenn der Artikel ein Konzept nennt, aber nicht darauf aufbaut, schafft ein Link einen unnötigen Ausgang.
• Wiederholte Erwähnungen: Lassen Sie den Begriff nach der ersten verlinkten Verwendung als Text stehen, es sei denn, eine lange, mehrteilige Seite schafft einen wirklich unabhängigen Lesekontext.
• Mehrdeutiger Ankertext: „Dieser Ansatz“, „Mehr erfahren“ und „Die Kennzahl“ identifizieren die Glossarentität nicht. Verlinken Sie den Begriff selbst.
• Kein kanonisches Ziel: Ersetzen Sie kein Suchergebnis, kein Tag-Archiv und keinen lose verwandten Artikel. Verwenden Sie einfachen Text, bis die kanonische Definition existiert.
• Bereits vollständig definiert: Wenn das Glossar keine nützliche Tiefe hinzufügt, ist ein zweiter Definitionsumweg möglicherweise unnötig.
• Kommerzielle Lenkung: Ein Glossarlink ist kein getarnter Produktaufruf. Produktseiten, Anmeldeabläufe und Preisseiten bedienen andere Leserabsichten.

Wenden Sie die gemeinsamen Element-Schreibregeln an, bevor Sie improvisieren. Deren Vorrangregel verlangt, dass Autoren ein Element nach seinem Zweck auswählen. Wenn der Zweck darin besteht, einen benannten Begriff mit seiner kanonischen Definition zu verbinden, verwenden Sie diese typisierte Beziehung statt eines generischen Inline-Links, der ähnlich gestaltet ist.

Wo es platziert werden soll

Platzieren Sie den Link bei der ersten sinnvollen Erwähnung im Fließtext: dem ersten Satz, der das Konzept im Sinne des Ziels verwendet. Wenn der Begriff zuerst im Titel oder in einer H2-Überschrift erscheint, verlinken Sie seine erste Verwendung im folgenden Absatz. Überschriften sollten stabile Abschnittsbezeichnungen bleiben und keine großen Navigationsziele sein.

Schreiben Sie bei einem Akronym zuerst den vollständigen Begriff, gefolgt von der Abkürzung, und verlinken Sie den vollständigen Begriff: Retrieval-Augmented Generation (RAG). Spätere Vorkommen können RAG ohne Link verwenden.

Platzieren Sie einen Glossar-Begriffslink nicht:

• innerhalb eines anderen Links, Buttons oder einer klickbaren Karte;
• neben einem zweiten Link mit demselben Ankertext;
• in Code, einer URL, einer E-Mail-Adresse oder wörtlichem Benutzereingabetext;
• in einer Überschrift, nur um die Ersterwähnungs-Regel zu erfüllen;
• in jeder Zeile einer Tabelle, wenn eine verlinkte Definition in der Einleitung den Begriff etablieren kann;
• unmittelbar neben einer Quellenangabe, wenn die beiden Ziele visuell oder funktional nicht unterscheidbar sind;
• innerhalb eines Tooltipp-Auslösers, der vom eigentlichen Link getrennt ist.

Wenn ein Satz mehrere unbekannte Begriffe enthält, verlinken Sie nur die Begriffe, die zum Verständnis dieses Satzes erforderlich sind. Drei oder mehr Glossarlinks in einem Satz sind ein Warnsignal, dass der Text zu viel Vokabular voraussetzt. Schreiben Sie den Satz um, definieren Sie ein Konzept direkt im Text oder teilen Sie die Erklärung auf, bevor Sie weitere Ausgänge hinzufügen.

Anatomie

Das beschriftete Exemplar hat sechs Bereiche:

1. Begriffsanker: der sichtbare Begriff oder vollständige ausgeschriebene Name, ohne „Mehr erfahren“.
2. Kanonisches Ziel: eine stabile Glossar-URL, die die Definition bereitstellt.
3. Kontextsatz: genügend Fließtext, um zu verstehen, warum der Begriff erscheint, auch wenn der Link nicht geöffnet wird.
4. Linkgestaltung: die standardmäßige Inline-Link-Behandlung der Website; Farbe ist nicht das einzige Erkennungsmerkmal.
5. Fokus-Indikator: ein sichtbarer Tastaturzustand, der nicht durch den Absatz oder Tooltipp abgeschnitten wird.
6. Optionaler Tooltipp: eine kurze Vorschau, die mit dem Link selbst verbunden ist, niemals ein separates nur-Symbol-Steuerelement.

Die Darstellung kann sich ändern, ohne den Anker, das Ziel oder das Verhalten der ersten Erwähnung zu verändern.

Gestaltungsbeispiele

Jede Variante bewahrt denselben semantischen Link.

Standardmäßiger Inline-Link: die erforderliche Basislinie. Sie funktioniert mit deaktiviertem JavaScript, im Lesemodus, in Druckanmerkungen und auf Geräten ohne Hover-Funktion.

Definitionstooltipp bei Fokus oder Hover: eine Erweiterung für dichte Bildungsinhalte. Die Vorschau umfasst ein bis zwei Sätze und enthält niemals Links, Buttons, Quellenangaben oder Formatierungssteuerelemente.

Mobil und Touch: Das erste Antippen folgt dem Link, es sei denn, das Produkt hat ein etabliertes, barrierefreies Aufdeckungsmuster. Zwingen Sie Benutzer nicht dazu, zu entdecken, dass ein Tippen eine Vorschau öffnet und ein zweites Tippen navigiert, es sei denn, diese Interaktion ist auf der gesamten Website konsistent und klar kommuniziert.

Dunkler Hintergrund: Link, Fokusring, Tooltipp-Text und Tooltipp-Rand behalten klaren Kontrast. Entfernen Sie die Unterstreichung nicht nur, weil die Akzentfarbe hell ist.

Parameter

Die kanonische URL und der sichtbare Anker sind inhaltliche Entscheidungen. Das Tooltipp-Verhalten gehört zum Renderer. Die Trennung dieser Quellen verhindert, dass eine optionale Oberflächenfunktion die Bedeutung des Links verändert.

Leiten Sie href niemals aus term ab: Homonyme können dieselbe Schreibweise haben, aber unterschiedliche Ziele erfordern. Übernehmen Sie einen Tooltipp aus dem Glossardatensatz nur, wenn seine Kurzdefinition für die Verwendung außerhalb der Seite geprüft wurde.

Syntax und Codebeispiele

Alle drei Formate bewahren einen normalen Link als Kern. Die benannten Felder sind ein portabler Vertrag; eine Plattform kann sie mit einem nativen Block, Plugin oder Vorverarbeitungsschritt rendern.

Portable Markdown-Direktive

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.

Wenn die Publikations-Pipeline keine Inline-Direktiven unterstützt, verwenden Sie gewöhnliches Markdown und lassen Sie den Tooltipp 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.

Diese Notation gibt die erforderliche Zuordnung an; sie verlangt nicht, dass Autoren einen neuen Shortcode in ein Projekt einführen, das Glossarlinks bereits über Markdown-Rendering oder Inhaltsvorverarbeitung handhabt. Der gerenderte Fallback muss immer ein gewöhnliches <a href>-Element sein.

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

Exportierte Inhalte müssen den Anker und href bewahren, selbst wenn Tooltipp-Metadaten nicht verfügbar sind.

Beispiele

Gut

Wählen Sie eine kanonische URL für im Wesentlichen ähnliche Seiten aus, sodass Indexierungssignale auf die bevorzugte Version verweisen.

Im gerenderten Artikel verlinkt „kanonische URL“ bei dieser ersten sinnvollen Verwendung auf /glossary/canonical-url/. Der Anker benennt die Entität exakt, der Satz gibt genügend lokalen Kontext, um weiterzulesen, und spätere Vorkommen bleiben reiner Text. Ein Leser kann entscheiden, ob die vollständige Definition notwendig ist.

Schlecht

Wählen Sie eine bevorzugte Seite für ähnliche Seiten aus. Ihre kanonische URL sollte dann in jedem Abschnitt auf die kanonische URL verweisen.

Dies scheitert zweimal. „Bevorzugte Seite“ ist eine verwandte Formulierung, aber nicht der exakte Begriff, den das Ziel definiert, sodass die Beziehung weniger explizit ist. Die Wiederholung des kanonischen URL-Links in jedem Abschnitt fügt Ausgänge hinzu, ohne Bedeutung zu verleihen. Die richtige Korrektur ist, „kanonische URL“ einmal bei ihrer ersten sinnvollen Verwendung zu verlinken und spätere Verwendungen unverlinkt zu lassen.

Ein weiteres schlechtes Muster ist ein Informationssymbol nach einem unverlinkten Begriff. Das Symbol verbirgt das Ziel vor Lesern, die den Linktext überfliegen, schafft ein kleines Touch-Ziel und kann den Tooltipp von der navigierbaren Glossarbeziehung trennen.

Schema-Markup und Barrierefreiheit

Ein Glossar-Begriffslink benötigt keinen eigenständigen Schema.org-Typ. Er bleibt ein Link innerhalb des umschließenden Article, TechArticle oder WebPage. Produzieren Sie kein DefinedTerm-, mentions- oder about-Markup für jeden Inline-Link; fügen Sie solche Beziehungen nur über ein konsistentes seitenweites Datenmodell hinzu, das durch sichtbare Inhalte gerechtfertigt ist.

Barrierefreiheit beginnt mit einem echten Anker. Er muss im Kontext verständlich sein, ohne Farbe allein unterscheidbar, per Tastatur erreichbar und sichtbar fokussiert sein. Wesentliche Informationen dürfen nicht nur im Tooltipp existieren.

Wenn ein Tooltipp implementiert ist, verknüpfen Sie ihn mit dem Anker über aria-describedby, solange er sichtbar ist. Öffnen Sie ihn sowohl bei Tastaturfokus als auch bei Maus-Hover, lassen Sie ihn geöffnet, während sich der Mauszeiger über dem Tooltipp bewegt, und ermöglichen Sie das Schließen mit Escape, ohne den Fokus zu verschieben. Platzieren Sie keine fokussierbaren Steuerelemente innerhalb eines Tooltipps. Verlassen Sie sich nicht auf das HTML-title-Attribut als Definitionsschnittstelle: dessen Timing, Darstellung, Touch-Unterstützung und Exposition gegenüber assistiven Technologien sind inkonsistent. Ein title kann ergänzend sein, aber er ist nicht der barrierefreie Name, die Beschreibung oder die kanonische Definition.

Der Link muss navigieren, wenn Skripte fehlschlagen. Bevorzugen Sie auf Touch-Geräten direkte Navigation gegenüber Hover-Imitation. Wenn die Erweiterung diese Anforderungen nicht erfüllen kann, liefern Sie den einfachen Link aus.

Schreibregeln

Verlinken Sie den exakten Begriff oder seine eindeutige vollständige Form. Halten Sie Anker auf ein bis acht Wörter und unter 80 Zeichen. Fügen Sie Artikel wie „ein“, „eine“ oder „der“ nur hinzu, wenn sie Teil eines Eigennamens sind. Setzen Sie nicht jeden Glossaranker fett; die standardmäßige Linkgestaltung kommuniziert bereits Interaktivität, und mehrfache Hervorhebungen machen technische Prosa unruhig.

Verwenden Sie standardmäßig einen Glossarlink pro Begriff pro Seite. Ein zweiter Link ist nur akzeptabel, wenn ein unabhängig konsumierter Inhalt – wie ein langer Anhang, eine eigenständige FAQ-Antwort oder ein eingebettetes Modul – sonst die Beziehung verlieren würde. Legen Sie keine feste Mindestanzahl von Glossarlinks fest. Eine klare Seite mit zwei notwendigen Begriffen ist besser als eine Seite mit zehn dekorativen Ausgängen.

Tooltipp-Definitionen sollten 40–180 Zeichen und nicht mehr als zwei Sätze umfassen. Geben Sie an, was der Begriff ist, nicht warum der Leser klicken sollte. Verwenden Sie neutrale, aussagende Sprache. Die Vorschau muss mit der aktuellen Definition des Ziels übereinstimmen und sollte nach Möglichkeit aus dem Glossardatensatz bezogen werden, damit Aktualisierungen nicht auseinanderdriften.

Setzen Sie niemals Folgendes innerhalb des Links oder Tooltipps:

• einen weiteren Link, Button, ein Formularsteuerelement oder ein interaktives Symbol;
• eine Verkaufsbehauptung oder einen Aufruf zum Handeln;
• eine Quellenliste oder Quellenangabe;
• ein Bild, Video, eine Tabelle, einen Codeblock oder eine mehrschrittige Anleitung;
• eine Definition, die mit der kanonischen Seite in Konflikt steht oder über diese hinausgeht;
• Anweisungen, die für die Erfüllung der Leseraufgabe wesentlich sind.

Überprüfen Sie Homonyme manuell. „Java“, „Conversion“ oder „Agent“ können unterschiedliche Entitäten bezeichnen. Der Satz und das Ziel müssen dieselbe Bedeutung auflösen. Wechseln Sie niemals die Ziele zur Linkverteilung; Kanonikalität ist der Punkt.

Beitragstypen, die es verwenden

Das postTypes[]-Frontmatter identifiziert die Formate, für die dieses Element ein dokumentierter Bestandteil des Contentsystems ist. Die Tabelle gibt an, wie jedes Format denselben Ersterwähnungs-Vertrag anwendet.

QA-Checkliste

• Kanonisches Ziel: der Pfad ist die eine Glossarseite, die die Definition besitzt; es ist keine Suche, kein Tag, kein Produkt und keine verwandte Artikel-URL.
• Ziel existiert: die Inhaltsdatei existiert jetzt oder der Pfad erscheint im genehmigten kanonischen Register für dieselbe Veröffentlichung.
• Bedeutung stimmt überein: der Anker und das Ziel beziehen sich auf denselben Sinn des Begriffs, einschließlich mehrdeutiger Akronyme und Homonyme.
• Erste sinnvolle Erwähnung: der Link erscheint im Fließtext vor späteren Verwendungen, nicht in einer Überschrift oder einem Codebeispiel, nur weil dieses Vorkommen in der Quellreihenfolge zuerst kam.
• Exakter Anker: Die verlinkten Wörter benennen den Begriff oder seine eindeutige vollständige Form; es gibt kein „Hier klicken“ oder einen vagen Ersatz.
• Lokaler Satz funktioniert: Ein Leser kann den Satz verstehen, ohne das Ziel zu öffnen oder den Tooltipp auszulösen.
• Ein-pro-Begriff-Standard: Wiederholte Vorkommen bleiben unverlinkt, es sei denn, ein dokumentierter unabhängiger Lesekontext rechtfertigt einen weiteren Link.
• Kein Link-Cluster: Der Satz und der Absatz bleiben lesbar; übermäßig viele unbekannte Begriffe werden umgeschrieben, nicht mit Links überdeckt.
• Tooltipp-Gleichheit: Jede Vorschau stimmt mit der kanonischen Definition überein und bleibt innerhalb von 40–180 Zeichen.
• Fortschrittliche Verbesserung: Der Anker funktioniert auch, wenn Skripte, Hover oder Tooltipp-Stile nicht verfügbar sind.
• Tastaturverhalten: Der Fokus ist sichtbar; der Tooltipp erscheint bei Fokus, kann mit Escape geschlossen werden und enthält keine fokussierbaren Steuerelemente.
• Touch-Verhalten: Der Link hat eine normale Zielgröße und erfordert weder Hover noch eine unerklärte Zwei-Tipp-Interaktion.
• Strukturierte-Daten-Zurückhaltung: Es wird keine nicht unterstützte Schema-Beziehung oder erfundener Elementtyp ausgegeben.
• Portable Ausgabe: Markdown, Hugo und WordPress bewahren denselben Begriff und dasselbe kanonische href, selbst wenn Tooltipp-Metadaten wegfallen.
• Screenshot-Status: Kommentare zu Bildschirmfotos bleiben nicht-rendering-Anweisungen, bis die benannten Assets existieren; es wird auf kein nicht vorhandenes Bild verwiesen.

FAQ

Die Academy-Vorlage rendert die geprüften Frontmatter-Fragen, die Zulässigkeit, erste Erwähnung, Tooltipp-Umfang, kanonische Konsistenz und Linkbegrenzungen abdecken.