Odkazy na glosářové termíny a tooltipy: Pravidla psaní

Odkaz na glosářový termín propojuje termín při jeho prvním smysluplném výskytu s jedinou stránkou, která vlastní jeho úplnou definici. Odkaz pomáhá čtenáři vyřešit neznámý jazyk, aniž by přerušil článek, a poskytuje crawlerům konzistentní vztah mezi termínem a jeho kanonickou entitní stránkou.

Kanonická URL je preferovaná verze stránky, pokud několik URL obsahuje stejný nebo v podstatě podobný obsah.

Tato věta je živým prvkem. Anchor text je přesný termín, cíl je jeho kanonický glosářový záznam a okolní věta zůstává srozumitelná i bez otevření odkazu. V systémech, které to podporují, může tentýž odkaz po najetí myší nebo při získání klávesového fokusu zobrazit krátký tooltip s definicí. Odkazovaná stránka – nikoli tooltip – zůstává zdrojem pravdy.

Proč na tomto prvku záleží

Čtenáři nepřicházejí se stejnou slovní zásobou. Specialista může rozpoznat „kanonickou URL" okamžitě, zatímco kupující nebo nový člen týmu může potřebovat definici. Vysvětlovat každý termín v závorkách zpomaluje prózu pro experty; nevysvětlovat žádný vylučuje začátečníky. Odkaz na glosářový termín vytváří tichý únikový východ: pokračujte, pokud je termín známý, nebo otevřete jeho definici, pokud není.

Pravidlo prvního výskytu je důležité, protože nejistota se kumuluje. Pokud čtenář špatně pochopí termín v druhém odstavci, každé pozdější tvrzení postavené na tomto termínu je hůře hodnotitelné. Odkazování prvního smysluplného výskytu vyřeší nejistotu dříve, než se rozšíří. Pravidlo neznamená „odkazuj první textovou shodu." Termín v titulku, navigačním popisku, ukázce kódu nebo upoutávce nemusí ještě nést význam použitý ve vysvětlení.

Strojová extrahovatelnost je schopnost softwaru zachovat vztah poté, co je prezentace odstraněna. Popisný anchor text a stabilní cíl vytvářejí explicitní hranu: tato stránka používá koncept a tato glosářová stránka jej definuje. Konzistentní hrany posilují, která URL vlastní definici. Nevytvářejí formální znalostní graf ani nezaručují viditelnost, ale snižují nejednoznačnost, kterou by crawler jinak řešil pouze z blízkosti.

Přeodkazování tyto výhody obrací. Když je každý opakovaný termín odkazován, stránka přestává signalizovat priority. Čtenáři čelí poli konkurenčních východů, uživatelé asistenčních technologií slyší stejný cíl opakovaně a stroje dostávají mnoho redundantních hran namísto malé sady promyšlených vztahů. Jeden kanonický odkaz při prvním smysluplném výskytu je tedy výchozím stavem, nikoli minimem, které by se mělo opakovat v každé sekci.

Kdy jej použít

Použijte tento prvek, když jsou splněny všechny tři podmínky:

1. Termín má kanonickou glosářovou stránku, nikoli několik téměř duplicitních definic.
2. Porozumění termínu materiálně pomáhá čtenáři porozumět aktuální stránce.
3. První smysluplné použití může nést popisný anchor text, aniž by deformovalo větu.

Silní kandidáti zahrnují odbornou terminologii, zkratky při prvním rozepsaném použití, pojmenované normy, metriky a slova, jejichž doménový význam se liší od běžného užití. Tooltip může zobrazit jednu krátkou definici; úplná glosářová stránka se zabývá hranicemi, příklady, zdroji a souvisejícími termíny.

Případy, které se blíží, ale přesto jsou chybné – zde je prvek nejčastěji zneužíván:

• Běžná slovní zásoba: neodkazujte známé slovo pouze proto, že glosářový záznam existuje.
• Okrajové zmínky: pokud článek zmiňuje koncept, ale nespoléhá se na něj, odkaz vytváří zbytečný východ.
• Opakované zmínky: po prvním odkazovaném použití ponechte termín jako text, pokud dlouhá, vícedílná stránka nevytváří skutečně nezávislý kontext čtení.
• Nejednoznačný anchor text: „tento přístup," „dozvědět se více" a „metrika" neidentifikují glosářovou entitu. Odkazujte samotný termín.
• Žádný kanonický cíl: nenahrazujte výsledek vyhledávání, archiv štítků nebo volně související článek. Používejte prostou prózu, dokud kanonická definice neexistuje.
• Definice již uvedena v plném rozsahu: pokud glosář nepřidává žádnou užitečnou hloubku, může být druhá definiční odbočka zbytečná.
• Komerční směrování: odkaz do glosáře není maskovaná výzva k akci produktu. Produktové stránky, registrační toky a ceníkové stránky slouží jiným záměrům čtenářů.

Před improvizací použijte sdílená pravidla psaní prvků . Jejich pravidlo priority vyžaduje, aby autoři vybírali prvek podle účelu. Pokud je účelem propojit pojmenovaný termín s jeho kanonickou definicí, použijte tento typový vztah namísto generického inline odkazu stylovaného tak, aby vypadal podobně.

Kam jej umístit

Umístěte odkaz na první smysluplný prozaický výskyt: první větu používající koncept v jeho cílovém významu. Pokud se termín poprvé objeví v titulku nebo H2, odkazujte jeho první použití v následujícím odstavci. Nadpisy by měly zůstat stabilními popisky sekcí, nikoli velkými navigačními cíli.

U zkratky napište plný termín následovaný zkratkou a odkazujte plný termín: retrieval-augmented generation (RAG). Pozdější výskyty mohou používat RAG bez odkazu.

Neumísťujte odkaz na glosářový termín:

• uvnitř jiného odkazu, tlačítka nebo klikací karty;
• vedle druhého odkazu na stejném anchor textu;
• v kódu, URL, e-mailové adrese nebo doslovném textu zadaném uživatelem;
• v nadpisu pouze za účelem splnění pravidla prvního výskytu;
• v každém řádku tabulky, pokud jedna odkazovaná definice v úvodu může termín ustanovit;
• bezprostředně vedle citační značky, pokud se dva cíle stanou vizuálně nebo funkčně nerozlišitelnými;
• uvnitř spouštěče tooltipu, který je oddělený od samotného odkazu.

Pokud věta obsahuje několik neznámých termínů, odkazujte pouze termíny potřebné k pochopení dané věty. Tři nebo více glosářových odkazů v jedné větě jsou varováním, že próza předpokládá příliš mnoho slovní zásoby. Přepište větu, definujte jeden pojem přímo nebo rozdělte vysvětlení, než přidáte další východy.

Anatomie

Označený vzorek má šest oblastí:

1. Kotva termínu: viditelný termín nebo úplný rozepsaný název, bez „dozvědět se více."
2. Kanonický cíl: jedna stabilní glosářová URL, která vlastní definici.
3. Kontextová věta: dostatek prózy k pochopení, proč se termín objevuje, i když odkaz není otevřen.
4. Styl odkazu: standardní inline ošetření odkazů na webu; barva není jediným vodítkem.
5. Indikátor fokusu: viditelný klávesový stav, který není oříznut odstavcem ani tooltipem.
6. Volitelný tooltip: krátký náhled vázaný na samotný odkaz, nikdy samostatné ovládání pouze s ikonou.

Prezentace se může měnit beze změny anchor textu, cíle nebo chování prvního výskytu.

Příklady designu

Každá varianta zachovává stejný sémantický odkaz.

Výchozí inline odkaz: požadovaný základ. Funguje s vypnutým JavaScriptem, v režimu čtení, v tiskových anotacích a na zařízeních bez hoveru.

Definiční tooltip při fokusu nebo hoveru: vylepšení pro hustý vzdělávací obsah. Náhled je jedna nebo dvě věty a nikdy neobsahuje odkazy, tlačítka, citace ani ovládací prvky formátování.

Mobil a dotyk: první klepnutí následuje odkaz, pokud produkt nemá zavedený, přístupný vzor pro rozbalení. Nenuťte uživatele zjišťovat, že první klepnutí otevře náhled a druhé klepnutí naviguje, pokud tato interakce není konzistentní napříč webem a jasně komunikovaná.

Tmavé pozadí: odkaz, fokusový kroužek, text tooltipu a ohraničení tooltipu si zachovávají jasný kontrast. Neodstraňujte podtržení jen proto, že je akcentní barva jasná.

Parametry

Kanonická URL a viditelný anchor text jsou obsahová rozhodnutí. Chování tooltipu náleží rendereru. Oddělení těchto zdrojů brání volitelné funkci rozhraní změnit význam odkazu.

Nikdy neodvozujte href z term: homonyma mohou sdílet pravopis, ale vyžadovat různé cíle. Načtěte tooltip z glosářového záznamu pouze tehdy, když je jeho krátká definice zkontrolována pro použití mimo stránku.

Syntaxe a příklady kódu

Všechny tři formáty zachovávají normální odkaz jako jádro. Pojmenovaná pole jsou přenosný kontrakt; platforma je může vykreslit pomocí nativního bloku, pluginu nebo kroku předzpracování.

Přenosná Markdown direktiva

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.

Pokud publikační pipeline nepodporuje inline direktivy, použijte běžný Markdown a vynechejte 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 specifikuje požadované mapování; nevyžaduje, aby autoři do projektu, který již zpracovává glosářové odkazy přes Markdown rendering nebo předzpracování obsahu, zaváděli nový shortcode. Vykreslený fallback musí být vždy běžný prvek <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í zachovat anchor text a href i v případě, že metadata tooltipu nejsou k dispozici.

Příklady

Dobře

Vyberte jednu kanonickou URL pro v podstatě podobné stránky, aby indexační signály směřovaly na preferovanou verzi.

Ve vykresleném článku odkazuje „kanonická URL" při tomto prvním smysluplném použití na /glossary/canonical-url/. Anchor text pojmenovává entitu přesně, věta poskytuje dostatek lokálního kontextu pro pokračování ve čtení a pozdější výskyty zůstávají prostým textem. Čtenář si může zvolit, zda je úplná definice nezbytná.

Špatně

Vyberte jednu preferovanou stránku pro podobné stránky. Vaše kanonická URL by pak měla v každé sekci odkazovat na kanonickou URL.

Toto selhává dvakrát. „Preferovaná stránka" je příbuzné znění, nikoli však přesný termín, který cíl definuje, takže vztah je méně explicitní. Opakování odkazu na kanonickou URL v každé sekci přidává východy bez přidání významu. Správná oprava je odkazovat „kanonická URL" jednou při jejím prvním smysluplném použití a pozdější použití ponechat neodkazovaná.

Dalším špatným vzorem je informační ikona po neodkazovaném termínu. Ikona skrývá cíl před čtenáři prohledávajícími text odkazů, vytváří malý dotykový cíl a může oddělit tooltip od navigovatelného glosářového vztahu.

Schema markup a přístupnost

Odkaz na glosářový termín nepotřebuje samostatný typ Schema.org. Zůstává odkazem uvnitř obalujícího Article, TechArticle nebo WebPage. Nevyrábějte DefinedTerm, mentions nebo about markup pro každý inline odkaz; přidávejte takové vztahy pouze prostřednictvím konzistentního datového modelu na úrovni stránky, který je odůvodněn viditelným obsahem.

Přístupnost začíná skutečnou kotvou. Musí být srozumitelná v kontextu, rozlišitelná pouze barvou, dosažitelná klávesnicí a viditelně fokusovaná. Podstatné informace nesmí existovat pouze v tooltipu.

Pokud je tooltip implementován, propojte jej s kotvou pomocí aria-describedby, dokud je viditelný. Otevřete jej při klávesovém fokusu i při hoveru myší, ponechte jej otevřený, dokud se kurzor pohybuje nad tooltipem, a umožněte jeho zavření klávesou Escape bez přesunu fokusu. Neumísťujte fokusovatelné ovládací prvky dovnitř tooltipu. Nespoléhejte na HTML atribut title jako rozhraní definice: jeho načasování, prezentace, podpora dotyku a vystavení asistenčním technologiím jsou nekonzistentní. Atribut title může být doplňkový, ale není přístupným názvem, popisem ani kanonickou definicí.

Odkaz musí navigovat, když skripty selžou. Na dotykových zařízeních upřednostněte přímou navigaci před imitací hoveru. Pokud vylepšení nemůže splnit tyto požadavky, doručte prostý odkaz.

Pravidla psaní

Odkazujte přesný termín nebo jeho jednoznačnou plnou formu. Udržujte anchor text na 1–8 slovech a pod 80 znaky. Členy jako „a" nebo „the" zahrňte pouze tehdy, jsou-li součástí vlastního jména. Nezvýrazňujte tučně každou glosářovou kotvu; standardní stylování odkazů již komunikuje interaktivitu a nahromaděné zvýraznění činí technickou prózu nepřehlednou.

Použijte jeden glosářový odkaz na termín na stránku jako výchozí. Druhý odkaz je přijatelný pouze tehdy, když by jinak nezávisle konzumovaný obsah – například dlouhý dodatek, samostatná odpověď FAQ nebo vložený modul – ztratil vztah. Nestanovujte pevný minimální počet glosářových odkazů. Jasná stránka se dvěma nezbytnými termíny je lepší než stránka s deseti dekorativními východy.

Tooltipové definice by měly mít 40–180 znaků a maximálně dvě věty. Uvádějte, co termín je, nikoli proč by na něj měl čtenář kliknout. Používejte neutrální, oznamovací jazyk. Náhled se musí shodovat s aktuální definicí cíle a měl by být pokud možno převzat z glosářového záznamu, aby se aktualizace nerozcházely.

Nikdy neumísťujte do odkazu nebo tooltipu:

• další odkaz, tlačítko, formulářový prvek nebo interaktivní ikonu;
• prodejní tvrzení nebo výzvu k akci;
• seznam citací nebo zdrojovou poznámku;
• obrázek, video, tabulku, blok kódu nebo vícestupňový postup;
• definici, která je v rozporu s kanonickou stránkou nebo ji rozšiřuje;
• instrukce, které jsou nezbytné pro dokončení čtenářova úkolu.

Kontrolujte homonyma ručně. „Java," „conversion" nebo „agent" mohou pojmenovávat různé entity. Věta a cíl musí vyjadřovat stejný význam. Nikdy nestřídejte cíle kvůli distribuci odkazů; kanonicita je klíčová.

Typy příspěvků, které jej používají

Pole postTypes[] v frontmatter identifikuje formáty, pro které je tento prvek zdokumentovanou součástí obsahového systému. Tabulka uvádí, jak každý formát aplikuje stejný kontrakt prvního výskytu.

QA checklist

• Kanonický cíl: cesta je jediná glosářová stránka, která vlastní definici; není to vyhledávání, štítek, produkt ani URL souvisejícího článku.
• Cíl existuje: soubor s obsahem existuje nyní nebo se cesta objevuje ve schváleném kanonickém registru pro stejné vydání.
• Význam odpovídá: anchor text a cíl odkazují na stejný význam termínu, včetně nejednoznačných zkratek a homonym.
• První smysluplný výskyt: odkaz se objevuje v próze před pozdějšími použitími, nikoli v nadpisu nebo ukázce kódu jen proto, že se daný výskyt objevil dříve v pořadí zdroje.
• Přesný anchor text: odkazovaná slova pojmenovávají termín nebo jeho úplnou jednoznačnou formu; není zde „klikněte zde" nebo vágní náhrada.
• Lokální věta funguje: čtenář může porozumět větě bez otevření cíle nebo spuštění tooltipu.
• Výchozí jeden na termín: opakované výskyty zůstávají neodkazované, pokud dokumentovaný nezávislý kontext čtení neospravedlňuje další odkaz.
• Žádný shluk odkazů: věta a odstavec zůstávají čitelné; nadměrné množství neznámých termínů je přepsáno, nikoli pokryto odkazy.
• Parita tooltipu: jakýkoli náhled souhlasí s kanonickou definicí a nepřekračuje 40–180 znaků.
• Progresivní vylepšení: anchor text stále funguje, když skripty, hover nebo stylování tooltipu nejsou k dispozici.
• Chování klávesnice: fokus je viditelný; tooltip se objeví při fokusu, lze jej zavřít klávesou Escape a neobsahuje žádné fokusovatelné ovládací prvky.
• Chování při dotyku: odkaz má normální velikost cíle a nevyžaduje hover nebo nevysvětlenou interakci dvou klepnutí.
• Zdrženlivost strukturovaných dat: není emitován žádný nepodporovaný schema vztah nebo vynalezený typ prvku.
• Přenosný výstup: Markdown, Hugo a WordPress zachovávají stejný termín a kanonické href, i když jsou metadata tooltipu vynechána.
• Stav screenshotů: komentáře k pořízení snímku zůstávají nevizuálními instrukcemi, dokud pojmenované assety neexistují; není odkazováno na žádný neexistující obrázek.

FAQ

Šablona academy vykresluje zkontrolované otázky z frontmatter týkající se způsobilosti, prvního výskytu, rozsahu tooltipu, kanonické konzistence a omezení odkazů.