Linkuri către termeni din glosar și tooltip-uri: Reguli de redactare

Un link către un termen din glosar conectează un termen la prima sa mențiune cu sens către singura pagină care deține definiția sa completă. Linkul ajută cititorul să rezolve un limbaj necunoscut fără a întrerupe articolul și oferă crawlerelor o relație consistentă între termen și pagina sa de entitate canonică.

Un URL canonic este versiunea preferată a unei pagini atunci când mai multe URL-uri conțin același conținut sau un conținut substanțial similar.

Această frază este elementul real. Ancora este termenul exact, destinația este intrarea sa canonică din glosar, iar fraza înconjurătoare rămâne inteligibilă fără a deschide linkul. Pe sistemele care îl suportă, același link poate afișa un tooltip cu o definiție scurtă la hover sau la focus cu tastatura. Pagina legată—nu tooltip-ul—rămâne sursa de adevăr.

De ce contează acest element

Cititorii nu sosesc cu același vocabular. Un specialist poate recunoaște „URL canonic” imediat, în timp ce un cumpărător sau un nou membru al echipei poate avea nevoie de o definiție. Explicarea fiecărui termen între paranteze încetinește proza pentru experți; explicarea niciunuia exclude nou-veniții. Un link către un termen din glosar creează o ieșire de siguranță discretă: continuă dacă termenul îți este familiar sau deschide definiția dacă nu.

Regula primei mențiuni contează deoarece incertitudinea se acumulează. Dacă un cititor înțelege greșit un termen în paragraful doi, orice afirmație ulterioară construită pe acel termen este mai greu de evaluat. Legarea primei apariții cu sens rezolvă incertitudinea înainte ca aceasta să se extindă. Regula nu înseamnă „leagă prima potrivire de șir.” Un termen dintr-un titlu, etichetă de navigare, eșantion de cod sau text de prezentare poate să nu poarte încă sensul folosit în explicație.

Extractibilitatea automată este capacitatea software-ului de a păstra o relație după ce prezentarea este îndepărtată. O ancoră descriptivă și o destinație stabilă creează o muchie explicită: această pagină folosește conceptul, iar acea pagină de glosar îl definește. Muchiile consistente consolidează care URL deține definiția. Ele nu creează un graf de cunoștințe formal și nici nu garantează vizibilitatea, dar reduc ambiguitatea pe care un crawler ar rezolva-o altfel doar din proximitate.

Supra-legarea inversează aceste beneficii. Când fiecare termen repetat este legat, pagina încetează să semnaleze prioritățile. Cititorii se confruntă cu un câmp de ieșiri concurente, utilizatorii de tehnologii asistive aud aceeași destinație în mod repetat, iar mașinile primesc multe muchii redundante în locul unui set restrâns de relații deliberate. Prin urmare, un link canonic la prima mențiune cu sens este valoarea implicită, nu un minim de repetat în fiecare secțiune.

Când să îl folosești

Folosește elementul atunci când toate cele trei condiții sunt îndeplinite:

1. Termenul are o pagină de glosar canonică, nu mai multe definiții aproape identice.
2. Înțelegerea termenului ajută în mod semnificativ cititorul să înțeleagă pagina curentă.
3. Prima utilizare cu sens poate purta o ancoră descriptivă fără a distorsiona fraza.

Candidați puternici includ terminologia de specialitate, acronimele la prima lor utilizare extinsă, standarde denumite, metrici și cuvinte al căror sens în domeniu diferă de cel cotidian. Un tooltip poate previzualiza o definiție scurtă; pagina de glosar completă gestionează limitele, exemplele, sursele și termenii conexi.

Cazurile aproape de limită sunt cele în care elementul este cel mai adesea folosit greșit:

• Vocabular obișnuit: nu lega un cuvânt familiar doar pentru că există o intrare în glosar.
• Mențiuni incidentale: dacă articolul numește un concept dar nu se bazează pe el, un link creează o ieșire inutilă.
• Mențiuni repetate: după prima utilizare legată, lasă termenul ca text, cu excepția cazului în care o pagină lungă, cu mai multe părți, creează un context de lectură cu adevărat independent.
• Text de ancoră ambiguu: „această abordare,” „află mai multe” și „metrica” nu identifică entitatea din glosar. Leagă termenul în sine.
• Fără destinație canonică: nu înlocui cu un rezultat de căutare, arhivă de etichete sau articol vag conex. Folosește proză simplă până când există definiția canonică.
• Definiție deja furnizată integral: dacă glosarul nu adaugă o profunzime utilă, un nou ocol definițional poate fi inutil.
• Dirijare comercială: un link de glosar nu este un îndemn voalat la acțiune pentru un produs. Paginile de produs, fluxurile de înregistrare și paginile de prețuri servesc intenții diferite ale cititorului.

Aplică regulile de redactare a elementelor comune înainte de a improviza. Regula lor de precedență impune autorilor să selecteze un element în funcție de scop. Dacă scopul este de a conecta un termen denumit la definiția sa canonică, folosește această relație tipizată în locul unui link inline generic stilizat să semene.

Unde să îl plasezi

Plasează linkul la prima mențiune cu sens din proză: prima frază care folosește conceptul în sensul destinației. Dacă termenul apare prima dată în titlu sau într-un H2, leagă prima sa utilizare din paragraful următor. Titlurile ar trebui să rămână etichete stabile de secțiune, nu ținte mari de navigare.

Pentru un acronim, scrie termenul complet urmat de abreviere și leagă termenul complet: generare augmentată cu regăsire (RAG). Aparițiile ulterioare pot folosi RAG fără link.

Nu plasa un link către un termen din glosar:

• în interiorul unui alt link, buton sau card clickabil;
• lângă un al doilea link pe același text de ancoră;
• în cod, URL, adresă de email sau text literal introdus de utilizator;
• într-un titlu doar pentru a satisface regula primei mențiuni;
• în fiecare rând al unui tabel atunci când o definiție legată în introducere poate stabili termenul;
• imediat lângă un marker de citare dacă cele două ținte devin vizual sau operațional indistincte;
• în interiorul unui declanșator de tooltip care este separat de linkul propriu-zis.

Dacă o frază conține mai mulți termeni necunoscuți, leagă doar termenii necesari pentru a înțelege acea frază. Trei sau mai multe linkuri de glosar într-o singură frază sunt un semn de avertizare că proza presupune prea mult vocabular. Rescrie fraza, definește un concept pe loc sau împarte explicația înainte de a adăuga mai multe ieșiri.

Anatomie

Specimenul etichetat are șase regiuni:

1. Ancora termenului: termenul vizibil sau denumirea completă extinsă, fără „află mai multe.”
2. Destinația canonică: un URL de glosar stabil care deține definiția.
3. Fraza de context: suficientă proză pentru a înțelege de ce apare termenul, chiar dacă linkul nu este deschis.
4. Stilizarea linkului: tratamentul standard al linkurilor inline ale site-ului; culoarea nu este singurul indiciu.
5. Indicator de focus: o stare vizibilă la tastatură care nu este tăiată de paragraf sau de tooltip.
6. Tooltip opțional: o previzualizare scurtă legată de linkul în sine, niciodată un control separat doar cu pictogramă.

Prezentarea se poate schimba fără a modifica ancora, destinația sau comportamentul primei mențiuni.

Exemple de design

Fiecare variantă păstrează același link semantic.

Link inline implicit: valoarea de bază obligatorie. Funcționează cu JavaScript dezactivat, în modul de citire, în adnotări tipărite și pe dispozitive fără hover.

Tooltip de definiție la focus sau hover: o îmbunătățire pentru conținut educațional dens. Previzualizarea are una sau două fraze și nu conține niciodată linkuri, butoane, citări sau elemente de formatare.

Mobil și atingere: prima atingere urmează linkul, cu excepția cazului în care produsul are un model stabilit și accesibil de dezvăluire. Nu face utilizatorii să descopere că o atingere deschide o previzualizare și o a doua atingeră navighează, decât dacă această interacțiune este consecventă pe întreg site-ul și comunicată clar.

Fundal închis: linkul, inelul de focus, textul tooltip-ului și limita tooltip-ului păstrează un contrast clar. Nu elimina sublinierea doar pentru că culoarea de accent este aprinsă.

Parametri

URL-ul canonic și ancora vizibilă sunt decizii de conținut. Comportamentul tooltip-ului aparține sistemului de randare. Separarea acestor surse împiedică o funcție opțională de interfață să schimbe sensul linkului.

Nu deduce niciodată href din term: omonimele pot împărtăși grafia necesitând totuși destinații diferite. Extrage un tooltip din înregistrarea de glosar numai atunci când definiția sa scurtă este revizuită pentru utilizare în afara paginii.

Sintaxă și exemple de cod

Toate cele trei formate păstrează un link normal ca element central. Câmpurile denumite sunt un contract portabil; o platformă le poate randa cu un bloc nativ, un plugin sau un pas de preprocesare.

Directivă Markdown portabilă

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.

Dacă pipeline-ul de publicare nu suportă directive inline, folosește Markdown obișnuit și omite tooltip-ul:

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.

Această notație specifică maparea necesară; nu impune autorilor să introducă un shortcode nou într-un proiect care gestionează deja linkurile de glosar prin randare Markdown sau preprocesare de conținut. Fallback-ul randat trebuie să fie întotdeauna un element obișnuit <a href>.

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

Conținutul exportat trebuie să păstreze ancora și href chiar și atunci când metadatele tooltip-ului nu sunt disponibile.

Exemple

Corect

Selectează un URL canonic pentru paginile substanțial similare, astfel încât semnalele de indexare să indice versiunea preferată.

În articolul randat, „URL canonic” face legătura către /glossary/canonical-url/ la această primă utilizare cu sens. Ancora denumește entitatea exact, fraza oferă suficient context local pentru a continua lectura, iar aparițiile ulterioare rămân text simplu. Cititorul poate alege dacă definiția completă este necesară.

Greșit

Selectează o pagină preferată pentru paginile similare. URL-ul tău canonic ar trebui apoi să facă referire la URL-ul canonic în fiecare secțiune.

Aceasta eșuează de două ori. „Pagină preferată” este o formulare conexă, dar nu termenul exact pe care îl definește destinația, astfel încât relația este mai puțin explicită. Repetarea linkului URL canonic în fiecare secțiune adaugă ieșiri fără a adăuga sens. Repararea corectă este de a lega „URL canonic” o singură dată la prima sa utilizare cu sens și a lăsa utilizările ulterioare nelegate.

Un alt model greșit este o pictogramă de informații după un termen nelegat. Pictograma ascunde destinația de cititorii care scanează textul linkului, creează o țintă tactilă mică și poate separa tooltip-ul de relația de glosar navigabilă.

Marcare Schema și accesibilitate

Un link către un termen din glosar nu necesită un tip Schema.org de sine stătător. Rămâne un link în interiorul Article, TechArticle sau WebPage care îl înconjoară. Nu fabrica marcare DefinedTerm, mentions sau about pentru fiecare link inline; adaugă astfel de relații doar printr-un model de date consistent la nivel de pagină, justificat de conținutul vizibil.

Accesibilitatea începe cu o ancoră reală. Aceasta trebuie să fie inteligibilă în context, distinsă fără doar culoare, accesibilă de la tastatură și focalizată vizibil. Informațiile esențiale nu pot exista doar în tooltip.

Dacă un tooltip este implementat, asociază-l cu ancora folosind aria-describedby în timp ce este vizibil. Deschide-l atât la focus cu tastatura, cât și la hover cu indicatorul, păstrează-l deschis în timp ce indicatorul se deplasează deasupra tooltip-ului și permite închiderea cu Escape fără a muta focusul. Nu plasa controale focalizabile în interiorul unui tooltip. Nu te baza pe atributul HTML title ca interfață de definiție: sincronizarea, prezentarea, suportul tactil și expunerea pentru tehnologiile asistive sunt inconsistente. Un title poate fi suplimentar, dar nu este numele accesibil, descrierea sau definiția canonică.

Linkul trebuie să navigheze atunci când scripturile eșuează. Pe dispozitive tactile, favorizează navigarea directă în locul imitării hover-ului. Dacă îmbunătățirea nu poate îndeplini aceste cerințe, livrează linkul simplu.

Reguli de redactare

Leagă termenul exact sau forma sa completă neambiguă. Menține ancorele între unu și opt cuvinte și sub 80 de caractere. Include articole precum „un”, „o” sau „the” doar atunci când fac parte dintr-un nume propriu. Nu îngroșa fiecare ancoră de glosar; stilizarea standard a linkurilor comunică deja interactivitatea, iar accentul suprapus face proza tehnică zgomotoasă.

Folosește un link de glosar per termen per pagină în mod implicit. Un al doilea link este acceptabil doar atunci când conținutul consumat independent—cum ar fi un anexă lungă, un răspuns FAQ de sine stătător sau un modul încorporat—ar pierde altfel relația. Nu stabili un număr minim fix de linkuri de glosar. O pagină clară cu doi termeni necesari este mai bună decât o pagină cu zece ieșiri decorative.

Definițiile din tooltip ar trebui să aibă 40–180 de caractere și cel mult două fraze. Enunță ce este termenul, nu de ce ar trebui să dea clic cititorul. Folosește un limbaj neutru, declarativ. Previzualizarea trebuie să fie de acord cu definiția curentă a destinației și ar trebui să fie preluată din înregistrarea de glosar atunci când este posibil, astfel încât actualizările să nu divergă.

Nu pune niciodată următoarele în interiorul linkului sau tooltip-ului:

• un alt link, buton, control de formular sau pictogramă interactivă;
• o afirmație de vânzare sau îndemn la acțiune;
• o listă de citări sau notă de sursă;
• o imagine, un videoclip, un tabel, un bloc de cod sau o procedură în mai mulți pași;
• o definiție care intră în conflict cu sau se extinde dincolo de pagina canonică;
• instrucțiuni care sunt esențiale pentru îndeplinirea sarcinii cititorului.

Revizuiește omonimele manual. „Java,” „conversie” sau „agent” pot denumi entități diferite. Fraza și destinația trebuie să rezolve același sens. Nu roti niciodată destinațiile pentru distribuirea linkurilor; canonicalitatea este scopul.

Tipuri de postări care îl folosesc

Frontmatter-ul postTypes[] identifică formatele pentru care acest element este o parte documentată a sistemului de conținut. Tabelul indică modul în care fiecare format aplică același contract al primei mențiuni.

Listă de verificare QA

• Destinație canonică: calea este singura pagină de glosar care deține definiția; nu este un URL de căutare, etichetă, produs sau articol conex.
• Destinația există: fișierul de conținut există acum sau calea apare în registrul canonic aprobat pentru aceeași versiune.
• Sensul se potrivește: ancora și destinația se referă la același sens al termenului, inclusiv acronime ambigue și omonime.
• Prima mențiune cu sens: linkul apare în proză înaintea utilizărilor ulterioare, nu într-un titlu sau eșantion de cod doar pentru că acea apariție a venit prima în ordinea sursei.
• Ancoră exactă: cuvintele legate denumesc termenul sau forma sa completă neambiguă; nu există „dă clic aici” sau înlocuitor vag.
• Fraza locală funcționează: un cititor poate înțelege fraza fără a deschide destinația sau a declanșa tooltip-ul.
• Implicit unu-per-termen: aparițiile repetate rămân nelegate, cu excepția cazului în care un context de lectură independent documentat justifică un alt link.
• Fără cluster de linkuri: fraza și paragraful rămân lizibile; termenii necunoscuți în exces sunt rescriși, nu acoperiți cu linkuri.
• Paritate tooltip: orice previzualizare este de acord cu definiția canonică și rămâne între 40–180 de caractere.
• Îmbunătățire progresivă: ancora funcționează și atunci când scripturile, hover-ul sau stilizarea tooltip-ului nu sunt disponibile.
• Comportament tastatură: focusul este vizibil; tooltip-ul apare la focus, poate fi închis cu Escape și nu conține controale focalizabile.
• Comportament tactil: linkul are o dimensiune normală a țintei și nu necesită hover sau o interacțiune neexplicată cu două atingeri.
• Restricție date structurate: nu este emisă nicio relație de schemă nesuportată sau tip de element inventat.
• Rezultat portabil: Markdown, Hugo și WordPress păstrează același termen și același href canonic, chiar dacă metadatele tooltip-ului sunt eliminate.
• Stare capturi de ecran: comentariile de captură rămân instrucțiuni care nu se randesc până când activele denumite nu există; nicio imagine inexistentă nu este referită.

FAQ

Șablonul academy randează întrebările din frontmatter revizuite, care acoperă eligibilitatea, prima mențiune, domeniul tooltip-ului, consistența canonică și limitele linkurilor.