Odkazy na glosárske výrazy a tooltipy: Pravidlá písania

Odkaz na glosársky výraz spája výraz pri jeho prvom zmysluplnom výskyte s jedinou stránkou, ktorá vlastní jeho kompletnú definíciu. Odkaz pomáha čitateľovi pochopiť neznámy jazyk bez prerušenia článku a poskytuje prehľadávačom konzistentný vzťah medzi výrazom a jeho kanonickou entitnou stránkou.

Kanonická URL je preferovaná verzia stránky, keď niekoľko URL obsahuje rovnaký alebo v podstate podobný obsah.

Táto veta je živý prvok. Anchor text je presný výraz, cieľ je jeho kanonický glosársky záznam a okolitá veta zostáva zrozumiteľná aj bez otvorenia odkazu. V systémoch, ktoré to podporujú, môže rovnaký odkaz pri hoveri alebo klávesnicovom zaostrení zobraziť krátky definičný tooltip. Stránka, na ktorú odkaz vedie — nie tooltip — zostáva zdrojom pravdy.

Prečo na tomto prvku záleží

Čitatelia neprichádzajú s rovnakou slovnou zásobou. Odborník môže okamžite rozpoznať „kanonická URL", zatiaľ čo kupujúci alebo nový člen tímu môže potrebovať definíciu. Vysvetľovanie každého výrazu v zátvorkách spomaľuje prózu pre expertov; nevysvetlenie žiadneho vylučuje nováčikov. Odkaz na glosársky výraz vytvára tichý núdzový východ: pokračujte, ak je výraz známy, alebo si otvorte jeho definíciu, ak nie je.

Pravidlo prvého výskytu je dôležité, pretože neistota sa znásobuje. Ak čitateľ nesprávne pochopí výraz v druhom odseku, každé neskoršie tvrdenie postavené na tomto výraze sa hodnotí ťažšie. Odkazovanie prvého zmysluplného výskytu odstráni neistotu skôr, než sa rozšíri. Toto pravidlo neznamená „odkazovať prvý reťazcový výskyt". Výraz v nadpise, navigačnom štítku, ukážke kódu alebo teaseri ešte nemusí niesť význam použitý vo vysvetlení.

Strojová extrahovateľnosť je schopnosť softvéru zachovať vzťah po odstránení prezentácie. Deskriptívny anchor text a stabilný cieľ vytvárajú explicitnú hranu: táto stránka používa pojem a táto glosárska stránka ho definuje. Konzistentné hrany posilňujú, ktorá URL vlastní definíciu. Nevytvárajú formálny znalostný graf ani nezaručujú viditeľnosť, ale znižujú nejednoznačnosť, ktorú by prehľadávač inak riešil len z blízkosti.

Nadmerné odkazovanie tieto výhody ruší. Keď je každý opakovaný výraz odkazovaný, stránka prestáva signalizovať priority. Čitatelia čelia poľu konkurenčných východov, používatelia asistenčných technológií počujú rovnaký cieľ opakovane a stroje dostávajú mnoho redundantných hrán namiesto malej sady zámerných vzťahov. Jeden kanonický odkaz pri prvom zmysluplnom výskyte je preto štandard, nie minimum, ktoré treba opakovať v každej sekcii.

Kedy ho použiť

Prvok použite, keď sú splnené všetky tri podmienky:

1. Výraz má kanonickú glosársku stránku, nie niekoľko takmer duplicitných definícií.
2. Pochopenie výrazu vecne pomáha čitateľovi pochopiť aktuálnu stránku.
3. Prvý zmysluplný výskyt môže niesť deskriptívny anchor text bez narušenia vety.

Silní kandidáti zahŕňajú odbornú terminológiu, skratky pri prvom rozvinutom použití, pomenované normy, metriky a slová, ktorých odborný význam sa líši od bežného používania. Tooltip môže zobraziť jednu krátku definíciu; úplná glosárska stránka sa venuje hraniciam, príkladom, zdrojom a súvisiacim výrazom.

Prípady takmer zásahu sú miesta, kde sa prvok najčastejšie zneužíva:

• Bežná slovná zásoba: neodkazujte známe slovo len preto, že existuje glosársky záznam.
• Okrajové zmienky: ak článok spomenie pojem, ale nespolieha sa naň, odkaz vytvára zbytočný východ.
• Opakované zmienky: po prvom odkazovanom použití ponechajte výraz ako text, pokiaľ dlhá viacdielna stránka nevytvára skutočne nezávislý kontext čítania.
• Nejednoznačný anchor text: „tento prístup", „zistite viac" a „metrika" neidentifikujú glosársku entitu. Odkazujte samotný výraz.
• Žiadny kanonický cieľ: nenahrádzajte výsledkom vyhľadávania, archívom štítkov alebo voľne súvisiacim článkom. Používajte obyčajnú prózu, kým kanonická definícia neexistuje.
• Definícia už poskytnutá v plnom rozsahu: ak glosár nepridáva žiadnu užitočnú hĺbku, druhý definičný odklon môže byť zbytočný.
• Komerčné smerovanie: odkaz na glosár nie je maskovaná výzva na akciu produktu. Produktové stránky, registračné toky a cenníky slúžia iným zámerom čitateľov.

Pred improvizáciou aplikujte spoločné pravidlá písania prvkov . Ich pravidlo priority vyžaduje, aby autori vyberali prvok podľa účelu. Ak je účelom spojiť pomenovaný výraz s jeho kanonickou definíciou, použite tento typový vzťah radšej než generický inline odkaz štylizovaný tak, aby vyzeral podobne.

Kam ho umiestniť

Umiestnite odkaz na prvý zmysluplný prozaický výskyt: prvú vetu používajúcu pojem v zmysle cieľovej stránky. Ak sa výraz prvýkrát objaví v názve alebo v H2, odkazujte jeho prvé použitie v nasledujúcom odseku. Nadpisy by mali zostať stabilnými sekčnými štítkami, nie veľkými navigačnými cieľmi.

Pri skratke napíšte celý výraz nasledovaný skratkou a odkazujte celý výraz: retrieval-augmented generation (RAG). Neskoršie výskyty môžu používať RAG bez odkazu.

Neumiestňujte odkaz na glosársky výraz:

• vnútri iného odkazu, tlačidla alebo klikateľnej karty;
• vedľa druhého odkazu na rovnakom anchor texte;
• v kóde, URL, e-mailovej adrese alebo užívateľom zadanom doslovnom texte;
• v nadpise len pre splnenie pravidla prvého výskytu;
• v každom riadku tabuľky, keď jedna odkazovaná definícia v úvode môže výraz stanoviť;
• hneď vedľa citačnej značky, ak sú dva ciele vizuálne alebo funkčne nerozoznateľné;
• vnútri spúšťača tooltipu, ktorý je oddelený od samotného odkazu.

Ak veta obsahuje niekoľko neznámych výrazov, odkazujte len výrazy potrebné na pochopenie tejto vety. Tri alebo viac glosárskych odkazov v jednej vete sú varovaním, že próza predpokladá príliš veľa slovnej zásoby. Prepíšte vetu, definujte jeden pojem priamo alebo rozdeľte vysvetlenie skôr, než pridáte ďalšie východy.

Anatómia

Označená vzorka má šesť oblastí:

1. Anchor text výrazu: viditeľný výraz alebo úplný rozvinutý názov bez „zistite viac".
2. Kanonický cieľ: jedna stabilná glosárska URL, ktorá vlastní definíciu.
3. Kontextová veta: dostatok prózy na pochopenie, prečo sa výraz vyskytuje, aj keď odkaz nie je otvorený.
4. Štýl odkazu: štandardné ošetrenie inline odkazu na webe; farba nie je jediným vodítkom.
5. Indikátor zaostrenia: viditeľný klávesnicový stav, ktorý nie je orezaný odsekom alebo tooltipom.
6. Voliteľný tooltip: krátky náhľad viazaný na samotný odkaz, nikdy samostatný ovládací prvok len s ikonou.

Prezentácia sa môže meniť bez zmeny anchor textu, cieľa alebo správania pri prvom výskyte.

Príklady dizajnu

Každá varianta zachováva rovnaký sémantický odkaz.

Predvolený inline odkaz: požadovaný základ. Funguje s vypnutým JavaScriptom, v režime čítania, v tlačových anotáciách a na zariadeniach bez hoveru.

Definičný tooltip pri zaostrení alebo hoveri: vylepšenie pre hustý vzdelávací obsah. Náhľad je jedna alebo dve vety a nikdy neobsahuje odkazy, tlačidlá, citácie ani formátovacie ovládacie prvky.

Mobil a dotyk: prvé ťuknutie nasleduje odkaz, pokiaľ produkt nemá zavedený, prístupný vzor zverejnenia. Nenúťte používateľov zisťovať, že jedno ťuknutie otvára náhľad a druhé ťuknutie naviguje, pokiaľ táto interakcia nie je konzistentná naprieč celým webom a jasne komunikovaná.

Tmavé pozadie: odkaz, zaostrovací krúžok, text tooltipu a ohraničenie tooltipu si zachovávajú jasný kontrast. Neodstraňujte podčiarknutie len preto, že je akcentová farba jasná.

Parametre

Kanonická URL a viditeľný anchor text sú obsahové rozhodnutia. Správanie tooltipu patrí renderovaciemu systému. Oddelenie týchto zdrojov zabraňuje tomu, aby voliteľná funkcia rozhrania menila význam odkazu.

Nikdy neodvodzujte href z term: homonymá môžu zdieľať pravopis, ale vyžadovať rôzne ciele. Preberajte tooltip z glosárskeho záznamu len vtedy, keď je jeho krátka definícia posúdená na použitie mimo stránky.

Syntax a príklady kódu

Všetky tri formáty zachovávajú normálny odkaz ako jadro. Pomenované polia sú prenosnou zmluvou; platforma ich môže vykresliť natívnym blokom, pluginom alebo krokom predspracovania.

Prenosná Markdown direktíva

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.

Ak publikačný pipeline nepodporuje inline direktívy, použite obyčajný Markdown a vynechajte 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.

Tento zápis špecifikuje požadované mapovanie; nevyžaduje, aby autori zavádzali nový shortcode do projektu, ktorý už spracúva glosárske odkazy cez Markdown rendering alebo predspracovanie obsahu. Vykreslený fallback musí byť vždy obyčajný prvok <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 -->

Exportovaný obsah musí zachovať anchor text a href, aj keď metadáta tooltipu nie sú k dispozícii.

Príklady

Dobrý príklad

Vyberte jednu kanonickú URL pre v podstate podobné stránky, aby indexačné signály smerovali na preferovanú verziu.

Vo vykreslenom článku „kanonická URL" odkazuje na /glossary/canonical-url/ pri tomto prvom zmysluplnom použití. Anchor text presne pomenúva entitu, veta poskytuje dostatok lokálneho kontextu na pokračovanie v čítaní a neskoršie výskyty zostávajú obyčajným textom. Čitateľ sa môže rozhodnúť, či je úplná definícia potrebná.

Zlý príklad

Vyberte jednu preferovanú stránku pre podobné stránky. Vaša kanonická URL by potom mala odkazovať na kanonickú URL v každej sekcii.

Toto zlyháva dvakrát. „Preferovaná stránka" je príbuzné znenie, ale nie presný výraz, ktorý cieľ definuje, takže vzťah je menej explicitný. Opakovanie odkazu na kanonickú URL v každej sekcii pridáva východy bez pridania významu. Správnou opravou je odkazovať „kanonickú URL" raz pri prvom zmysluplnom použití a neskoršie použitia nechať neodkazované.

Ďalším zlým vzorom je informačná ikona po neodkazovanom výraze. Ikona skrýva cieľ pred čitateľmi, ktorí skenujú text odkazu, vytvára malý dotykový cieľ a môže oddeliť tooltip od navigovateľného glosárskeho vzťahu.

Schema markup a prístupnosť

Odkaz na glosársky výraz nepotrebuje samostatný typ Schema.org. Zostáva odkazom v rámci obklopujúceho Article, TechArticle alebo WebPage. Nevytvárajte markup DefinedTerm, mentions ani about pre každý inline odkaz; pridávajte takéto vzťahy len prostredníctvom konzistentného dátového modelu na úrovni stránky, odôvodneného viditeľným obsahom.

Prístupnosť začína skutočným anchor textom. Musí byť zrozumiteľný v kontexte, rozoznateľný bez farby samotnej, dosiahnuteľný klávesnicou a viditeľne zaostrený. Nevyhnutné informácie nemôžu existovať len v tooltipe.

Ak je tooltip implementovaný, prepojte ho s anchor textom pomocou aria-describedby, kým je viditeľný. Otvorte ho pri klávesnicovom zaostrení aj pri hoveri myšou, nechajte ho otvorený, kým sa kurzor pohybuje nad tooltipom, a umožnite jeho zatvorenie klávesom Escape bez presunu zaostrenia. Neumiestňujte zaostrovateľné ovládacie prvky do tooltipu. Nespoliehajte sa na HTML atribút title ako definičné rozhranie: jeho načasovanie, prezentácia, dotyková podpora a vystavenie asistenčným technológiám sú nejednotné. title môže byť doplnkový, ale nie je prístupným názvom, popisom ani kanonickou definíciou.

Odkaz musí navigovať, keď zlyhajú skripty. Na dotykových zariadeniach uprednostnite priamu navigáciu pred imitáciou hoveru. Ak vylepšenie nedokáže splniť tieto požiadavky, dodajte obyčajný odkaz.

Pravidlá písania

Odkazujte presný výraz alebo jeho jednoznačnú plnú formu. Udržujte anchor text na 1–8 slovách a pod 80 znakmi. Zahrňte členy ako „a" alebo „the" len vtedy, keď sú súčasťou vlastného mena. Netučnite každý glosársky anchor text; štandardné štylovanie odkazu už komunikuje interaktivitu a nahromadené zvýraznenie robí technickú prózu hlučnou.

Používajte jeden glosársky odkaz na výraz na stránku ako štandard. Druhý odkaz je prijateľný len vtedy, keď by inak nezávisle konzumovaný obsah — ako dlhý dodatok, samostatná odpoveď FAQ alebo vložený modul — stratil vzťah. Nestanovujte pevný minimálny počet glosárskych odkazov. Jasná stránka s dvoma nevyhnutnými výrazmi je lepšia ako stránka s desiatimi dekoratívnymi východmi.

Definície v tooltipoch by mali mať 40–180 znakov a najviac dve vety. Uveďte, čo výraz je, nie prečo by mal čitateľ kliknúť. Používajte neutrálny, oznamovací jazyk. Náhľad sa musí zhodovať s aktuálnou definíciou cieľa a mal by byť podľa možnosti prevzatý z glosárskeho záznamu, aby sa aktualizácie neodchyľovali.

Nikdy nedávajte do odkazu alebo tooltipu:

• ďalší odkaz, tlačidlo, formulárový prvok alebo interaktívnu ikonu;
• predajné tvrdenie alebo výzvu na akciu;
• zoznam citácií alebo poznámku pod čiarou;
• obrázok, video, tabuľku, blok kódu alebo viackrokový postup;
• definíciu, ktorá je v rozpore s kanonickou stránkou alebo ju rozširuje;
• inštrukcie, ktoré sú nevyhnutné na splnenie čitateľovej úlohy.

Kontrolujte homonymá manuálne. „Java", „conversion" alebo „agent" môžu pomenúvať rôzne entity. Veta a cieľ musia riešiť rovnaký význam. Nikdy nemeňte ciele kvôli distribúcii odkazov; kanonickosť je podstatou.

Typy príspevkov, ktoré ho používajú

Pole postTypes[] v frontmatter identifikuje formáty, pre ktoré je tento prvok zdokumentovanou súčasťou obsahového systému. Tabuľka uvádza, ako každý formát aplikuje rovnakú zmluvu prvého výskytu.

QA kontrolný zoznam

• Kanonický cieľ: cesta je jediná glosárska stránka, ktorá vlastní definíciu; nie je to URL vyhľadávania, štítku, produktu ani súvisiaceho článku.
• Cieľ existuje: súbor s obsahom existuje teraz alebo sa cesta nachádza v schválenej kanonickej registrácii pre rovnaké vydanie.
• Význam sa zhoduje: anchor text a cieľ odkazujú na rovnaký význam výrazu vrátane nejednoznačných skratiek a homoným.
• Prvý zmysluplný výskyt: odkaz sa objavuje v próze pred neskoršími použitiami, nie v nadpise alebo ukážke kódu len preto, že sa vyskytol prvý v poradí v zdroji.
• Presný anchor text: odkazované slová pomenúvajú výraz alebo jeho úplnú jednoznačnú formu; neexistuje „kliknite sem" ani vágna náhrada.
• Lokálna veta funguje: čitateľ rozumie vete bez otvorenia cieľa alebo spustenia tooltipu.
• Štandard jeden na výraz: opakované výskyty zostávajú neodkazované, pokiaľ zdokumentovaný nezávislý kontext čítania neodôvodňuje ďalší odkaz.
• Žiadny zhluk odkazov: veta a odsek zostávajú čitateľné; nadmerné neznáme výrazy sú prepísané, nie prekryté odkazmi.
• Parita tooltipu: akýkoľvek náhľad sa zhoduje s kanonickou definíciou a zostáva v rozmedzí 40–180 znakov.
• Progresívne vylepšenie: anchor text funguje aj vtedy, keď skripty, hover alebo štylovanie tooltipu nie sú k dispozícii.
• Klávesnicové správanie: zaostrenie je viditeľné; tooltip sa zobrazí pri zaostrení, dá sa zatvoriť klávesom Escape a neobsahuje zaostrovateľné ovládacie prvky.
• Dotykové správanie: odkaz má normálnu veľkosť cieľa a nevyžaduje hover ani nevysvetlenú dvojťukovú interakciu.
• Zdržanlivosť pri štruktúrovaných dátach: nie je emitovaný žiadny nepodporovaný schema vzťah ani vymyslený typ prvku.
• Prenosný výstup: Markdown, Hugo a WordPress zachovávajú rovnaký výraz a kanonické href, aj keď sú metadáta tooltipu vynechané.
• Stav snímok obrazovky: komentáre k snímkam zostávajú inštrukciami bez vykreslenia, kým pomenované assety neexistujú; nie je odkazovaný žiadny neexistujúci obrázok.

FAQ

Akademická šablóna vykresľuje recenzované otázky z frontmatter týkajúce sa oprávnenosti, prvého výskytu, rozsahu tooltipu, kanonickej konzistentnosti a limitov odkazov.