Linki do haseł słownikowych i podpowiedzi: zasady pisania

Link do hasła słownikowego łączy termin przy jego pierwszym znaczącym użyciu z jedną stroną, która zawiera jego pełną definicję. Link pomaga czytelnikowi zrozumieć nieznane słownictwo bez przerywania artykułu, a robotom indeksującym daje spójną relację między terminem a jego kanoniczną stroną bytu.

Kanoniczny URL to preferowana wersja strony, gdy kilka adresów URL zawiera tę samą lub w znacznym stopniu podobną treść.

To zdanie jest żywym elementem. Kotwica to dokładny termin, celem jest jego kanoniczny wpis słownikowy, a otaczające zdanie pozostaje zrozumiałe bez otwierania linku. W systemach, które to obsługują, ten sam link może wyświetlać krótką podpowiedź z definicją po najechaniu kursorem lub po focusie klawiaturowym. Strona docelowa — a nie podpowiedź — pozostaje źródłem prawdy.

Dlaczego ten element jest ważny

Czytelnicy nie dysponują tym samym słownictwem. Specjalista może od razu rozpoznać „kanoniczny URL", podczas gdy kupujący lub nowy członek zespołu może potrzebować definicji. Wyjaśnianie każdego terminu w nawiasie spowalnia tekst skierowany do ekspertów; niewyjaśnianie niczego wyklucza nowicjuszy. Link do hasła słownikowego tworzy cichą ścieżkę ucieczki: kontynuuj, jeśli termin jest znany, lub otwórz jego definicję, jeśli nie jest.

Zasada pierwszego użycia jest istotna, ponieważ niepewność narasta. Jeśli czytelnik źle zrozumie termin w drugim akapicie, każde późniejsze stwierdzenie oparte na tym terminie jest trudniejsze do oceny. Linkowanie pierwszego znaczącego wystąpienia usuwa niepewność, zanim się rozprzestrzeni. Zasada nie oznacza „linkuj pierwsze dopasowanie tekstowe". Termin w tytule, etykiecie nawigacyjnej, przykładzie kodu lub zajawce może nie nieść jeszcze znaczenia użytego w wyjaśnieniu.

Możliwość ekstrakcji maszynowej to zdolność oprogramowania do zachowania relacji po usunięciu prezentacji. Opisowa kotwica i stabilny cel tworzą jawną krawędź: ta strona używa pojęcia, a strona słownikowa je definiuje. Spójne krawędzie wzmacniają, który URL jest właścicielem definicji. Nie tworzą formalnego grafu wiedzy ani nie gwarantują widoczności, ale redukują niejednoznaczność, którą robot indeksujący musiałby inaczej rozwiązywać wyłącznie na podstawie bliskości tekstu.

Nadmierne linkowanie odwraca te korzyści. Gdy każdy powtórzony termin jest linkowany, strona przestaje sygnalizować priorytety. Czytelnik widzi pole konkurujących wyjść, użytkownicy technologii asystujących słyszą wielokrotnie ten sam cel, a maszyny otrzymują wiele zbędnych krawędzi zamiast małego zestawu celowych relacji. Jeden kanoniczny link przy pierwszym znaczącym użyciu jest zatem domyślną praktyką, a nie minimum do powtarzania w każdej sekcji.

Kiedy go używać

Używaj elementu, gdy spełnione są wszystkie trzy warunki:

1. Termin ma kanoniczną stronę słownikową, a nie kilka prawie identycznych definicji.
2. Zrozumienie terminu w istotny sposób pomaga czytelnikowi zrozumieć bieżącą stronę.
3. Pierwsze znaczące użycie może nieść opisową kotwicę bez zniekształcania zdania.

Dobrymi kandydatami są specjalistyczna terminologia, akronimy przy pierwszym rozwinięciu, nazwane normy, metryki oraz słowa, których znaczenie dziedzinowe różni się od codziennego. Podpowiedź może wyświetlać podgląd jednej krótkiej definicji; pełna strona słownikowa zawiera granice, przykłady, źródła i terminy pokrewne.

Przypadki graniczne, w których element jest najczęściej nadużywany:

• Zwykłe słownictwo: nie linkuj znajomego słowa tylko dlatego, że istnieje wpis słownikowy.
• Poboczne wzmianki: jeśli artykuł wymienia pojęcie, ale na nim nie polega, link tworzy niepotrzebne wyjście.
• Wielokrotne użycia: po pierwszym linkowanym użyciu pozostaw termin jako zwykły tekst, chyba że długa, wieloczęściowa strona tworzy naprawdę niezależny kontekst czytelniczy.
• Niejednoznaczna kotwica: „to podejście", „dowiedz się więcej" i „metryka" nie identyfikują bytu słownikowego. Linkuj sam termin.
• Brak kanonicznego celu: nie zastępuj go wynikiem wyszukiwania, archiwum tagów ani luźno powiązanym artykułem. Używaj zwykłego tekstu, dopóki kanoniczna definicja nie istnieje.
• Definicja już podana w pełni: jeśli słownik nie dodaje użytecznej głębi, dodatkowa definicyjna dygresja może być niepotrzebna.
• Kierowanie komercyjne: link słownikowy nie jest zakamuflowanym wezwaniem do działania. Strony produktów, formularze rejestracji i strony cenowe służą innym intencjom czytelnika.

Zastosuj wspólne zasady pisania elementów przed improwizacją. Ich reguła pierwszeństwa wymaga od autorów wyboru elementu według przeznaczenia. Jeśli celem jest połączenie nazwanego terminu z jego kanoniczną definicją, użyj tej typowanej relacji, a nie ogólnego linku inline stylizowanego na podobieństwo.

Gdzie go umieścić

Umieść link przy pierwszym znaczącym użyciu w treści: pierwszym zdaniu używającym pojęcia w znaczeniu zgodnym z celem. Jeśli termin pojawia się najpierw w tytule lub nagłówku H2, linkuj jego pierwsze użycie w następnym akapicie. Nagłówki powinny pozostać stabilnymi etykietami sekcji, a nie dużymi celami nawigacyjnymi.

W przypadku akronimu napisz pełny termin, a następnie skrót i linkuj pełny termin: retrieval-augmented generation (RAG). Późniejsze wystąpienia mogą używać RAG bez linku.

Nie umieszczaj linku do hasła słownikowego:

• wewnątrz innego linku, przycisku lub klikalnej karty;
• obok drugiego linku o tym samym tekście kotwicy;
• w kodzie, adresie URL, adresie e-mail ani dosłownym tekście wprowadzonym przez użytkownika;
• w nagłówku wyłącznie w celu spełnienia zasady pierwszego użycia;
• w każdym wierszu tabeli, gdy jedna linkowana definicja we wprowadzeniu może ustanowić termin;
• bezpośrednio obok znacznika cytowania, jeśli dwa cele stają się wizualnie lub operacyjnie nierozróżnialne;
• wewnątrz wyzwalacza podpowiedzi, który jest oddzielony od właściwego linku.

Jeśli zdanie zawiera kilka nieznanych terminów, linkuj tylko te potrzebne do zrozumienia tego zdania. Trzy lub więcej linków słownikowych w jednym zdaniu to sygnał ostrzegawczy, że tekst zakłada zbyt duże słownictwo. Przepisz zdanie, zdefiniuj jedno pojęcie na miejscu lub podziel wyjaśnienie, zanim dodasz więcej wyjść.

Anatomia

Oznaczony okaz ma sześć regionów:

1. Kotwica terminu: widoczny termin lub pełna rozwinięta nazwa, bez „dowiedz się więcej".
2. Cel kanoniczny: jeden stabilny URL słownikowy, który jest właścicielem definicji.
3. Zdanie kontekstowe: wystarczająco dużo tekstu, aby zrozumieć, dlaczego termin się pojawia, nawet jeśli link nie jest otwierany.
4. Stylizacja linku: standardowe oznakowanie linku inline w witrynie; kolor nie jest jedyną wskazówką.
5. Wskaźnik focusu: widoczny stan klawiaturowy, który nie jest obcięty przez akapit ani podpowiedź.
6. Opcjonalna podpowiedź: krótki podgląd powiązany z samym linkiem, nigdy osobna kontrolka tylko z ikoną.

Prezentacja może się zmieniać bez zmiany kotwicy, celu ani zachowania pierwszego użycia.

Przykłady projektowe

Każdy wariant zachowuje ten sam semantyczny link.

Domyślny link inline: wymagana podstawa. Działa z wyłączonym JavaScriptem, w trybie czytnika, w adnotacjach wydruku i na urządzeniach bez funkcji najechania.

Podpowiedź definicji przy focusie lub najechaniu: ulepszenie dla gęstych treści edukacyjnych. Podgląd to jedno lub dwa zdania i nigdy nie zawiera linków, przycisków, cytowań ani elementów formatowania.

Mobilne i dotykowe: pierwsze dotknięcie prowadzi do linku, chyba że produkt ma ustalony, dostępny wzorzec ujawniania. Nie zmuszaj użytkowników do odkrywania, że jedno dotknięcie otwiera podgląd, a drugie nawiguje, chyba że ta interakcja jest spójna w całej witrynie i jasno zakomunikowana.

Ciemne tło: link, pierścień focusu, tekst podpowiedzi i obramowanie podpowiedzi zachowują wyraźny kontrast. Nie usuwaj podkreślenia tylko dlatego, że kolor akcentu jest jasny.

Parametry

Kanoniczny URL i widoczna kotwica to decyzje dotyczące treści. Zachowanie podpowiedzi należy do renderera. Rozdzielenie tych źródeł zapobiega zmianie znaczenia linku przez opcjonalną funkcję interfejsu.

Nigdy nie wnioskuj href z term: homonimy mogą mieć tę samą pisownię, ale wymagać różnych celów. Pobieraj podpowiedź z rekordu słownikowego tylko wtedy, gdy jej krótka definicja została zweryfikowana pod kątem użycia poza stroną.

Składnia i przykłady kodu

Wszystkie trzy formaty zachowują zwykły link jako rdzeń. Nazwane pola są przenośnym kontraktem; platforma może je renderować za pomocą natywnego bloku, wtyczki lub etapu przetwarzania wstępnego.

Przenośna dyrektywa Markdown

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.

Jeśli potok publikacji nie obsługuje dyrektyw inline, użyj zwykłego Markdown i pomiń podpowiedź:

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.

Ten zapis określa wymagane mapowanie; nie wymaga od autorów wprowadzania nowego shortcode’u do projektu, który już obsługuje linki słownikowe przez renderowanie Markdown lub wstępne przetwarzanie treści. Renderowany fallback musi zawsze być zwykłym elementem <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 -->

Eksportowana treść musi zachować kotwicę i href, nawet gdy metadane podpowiedzi są niedostępne.

Przykłady

Prawidłowo

Wybierz jeden kanoniczny URL dla w znacznym stopniu podobnych stron, aby sygnały indeksowania wskazywały preferowaną wersję.

W opublikowanym artykule „kanoniczny URL" linkuje do /glossary/canonical-url/ przy tym pierwszym znaczącym użyciu. Kotwica nazywa byt dokładnie, zdanie daje wystarczająco dużo lokalnego kontekstu, by kontynuować czytanie, a późniejsze wystąpienia pozostają zwykłym tekstem. Czytelnik może wybrać, czy pełna definicja jest potrzebna.

Nieprawidłowo

Wybierz jedną preferowaną stronę dla podobnych stron. Twój kanoniczny URL powinien następnie odnosić się do kanonicznego URL w każdej sekcji.

To zawodzi dwukrotnie. „Preferowana strona" to pokrewne sformułowanie, ale nie dokładny termin, który cel definiuje, więc relacja jest mniej wyraźna. Powtarzanie linku kanonicznego URL w każdej sekcji dodaje wyjścia bez dodawania znaczenia. Prawidłową naprawą jest linkowanie „kanoniczny URL" raz przy pierwszym znaczącym użyciu i pozostawienie późniejszych wystąpień bez linku.

Innym złym wzorcem jest ikona informacyjna po nielinkowanym terminie. Ikona ukrywa cel przed czytelnikami skanującymi tekst linku, tworzy mały cel dotykowy i może oddzielić podpowiedź od nawigowalnej relacji słownikowej.

Znaczniki schematu i dostępność

Link do hasła słownikowego nie potrzebuje samodzielnego typu Schema.org. Pozostaje linkiem wewnątrz otaczającego Article, TechArticle lub WebPage. Nie twórz znaczników DefinedTerm, mentions ani about dla każdego linku inline; dodawaj takie relacje tylko przez spójny model danych na poziomie strony, uzasadniony widoczną treścią.

Dostępność zaczyna się od prawdziwej kotwicy. Musi być zrozumiała w kontekście, rozróżnialna bez samego koloru, osiągalna klawiaturą i widocznie oznaczona focusem. Niezbędne informacje nie mogą istnieć wyłącznie w podpowiedzi.

Jeśli podpowiedź jest zaimplementowana, powiąż ją z kotwicą za pomocą aria-describedby, gdy jest widoczna. Otwieraj ją zarówno przy focusie klawiaturowym, jak i najechaniu kursorem, utrzymuj ją otwartą, gdy kursor porusza się nad podpowiedzią, i pozwól na zamknięcie klawiszem Escape bez przenoszenia focusu. Nie umieszczaj elementów możliwych do focusowania wewnątrz podpowiedzi. Nie polegaj na atrybucie HTML title jako interfejsie definicji: jego czasowanie, prezentacja, obsługa dotykowa i ekspozycja dla technologii asystujących są niespójne. Atrybut title może być uzupełnieniem, ale nie jest dostępną nazwą, opisem ani kanoniczną definicją.

Link musi nawigować, gdy skrypty zawiodą. Na urządzeniach dotykowych preferuj bezpośrednią nawigację nad imitacją najechania. Jeśli ulepszenie nie może spełnić tych wymagań, wyślij zwykły link.

Zasady pisania

Linkuj dokładny termin lub jego jednoznaczną pełną formę. Utrzymuj kotwice w zakresie od jednego do ośmiu słów i poniżej 80 znaków. Dołączaj rodzajniki takie jak „a" lub „the" tylko wtedy, gdy są częścią nazwy własnej. Nie pogrubiaj każdej kotwicy słownikowej; standardowa stylizacja linku już komunikuje interaktywność, a nawarstwione podkreślenia czynią tekst techniczny hałaśliwym.

Domyślnie używaj jednego linku słownikowego na termin na stronę. Drugi link jest akceptowalny tylko wtedy, gdy niezależnie konsumowana treść — taka jak długi dodatek, samodzielna odpowiedź FAQ lub osadzony moduł — w przeciwnym razie straciłaby relację. Nie ustalaj stałej minimalnej liczby linków słownikowych. Jasna strona z dwoma niezbędnymi terminami jest lepsza niż strona z dziesięcioma dekoracyjnymi wyjściami.

Definicje w podpowiedziach powinny mieć 40–180 znaków i nie więcej niż dwa zdania. Mów, czym termin jest, a nie dlaczego czytelnik powinien kliknąć. Używaj neutralnego, oznajmującego języka. Podgląd musi być zgodny z bieżącą definicją celu i powinien pochodzić z rekordu słownikowego, gdy to możliwe, aby aktualizacje nie rozchodziły się.

Nigdy nie umieszczaj wewnątrz linku lub podpowiedzi:

• innego linku, przycisku, kontrolki formularza ani interaktywnej ikony;
• roszczenia sprzedażowego ani wezwania do działania;
• listy cytowań ani przypisu źródłowego;
• obrazu, wideo, tabeli, bloku kodu ani wieloetapowej procedury;
• definicji, która jest sprzeczna z kanoniczną stroną lub wykracza poza nią;
• instrukcji niezbędnych do wykonania zadania czytelnika.

Sprawdzaj homonimy ręcznie. „Java", „konwersja" lub „agent" mogą nazywać różne byty. Zdanie i cel muszą wyrażać to samo znaczenie. Nigdy nie zmieniaj celów w celu dystrybucji linków; kanoniczność jest sednem.

Typy wpisów, które go używają

Frontmatter postTypes[] identyfikuje formaty, dla których ten element jest udokumentowaną częścią systemu treści. Tabela określa, jak każdy format stosuje tę samą umowę pierwszego użycia.

Lista kontrolna QA

• Cel kanoniczny: ścieżka to jedna strona słownikowa będąca właścicielem definicji; nie jest to URL wyszukiwania, tagu, produktu ani powiązanego artykułu.
• Cel istnieje: plik treści istnieje teraz lub ścieżka pojawia się w zatwierdzonym rejestrze kanonicznym dla tej samej wersji wydania.
• Znaczenie zgodne: kotwica i cel odnoszą się do tego samego znaczenia terminu, w tym niejednoznacznych akronimów i homonimów.
• Pierwsze znaczące użycie: link pojawia się w treści przed późniejszymi użyciami, nie w nagłówku ani przykładzie kodu tylko dlatego, że to wystąpienie było pierwsze w kolejności źródłowej.
• Dokładna kotwica: linkowane słowa nazywają termin lub jego pełną jednoznaczną formę; nie ma „kliknij tutaj" ani niejasnego substytutu.
• Lokalne zdanie działa: czytelnik może zrozumieć zdanie bez otwierania celu ani wywoływania podpowiedzi.
• Domyślnie jeden na termin: powtórzone wystąpienia pozostają bez linku, chyba że udokumentowany niezależny kontekst czytelniczy uzasadnia kolejny link.
• Brak klastra linków: zdanie i akapit pozostają czytelne; nadmierna liczba nieznanych terminów jest przepisana, a nie pokryta linkami.
• Zgodność podpowiedzi: każdy podgląd jest zgodny z definicją kanoniczną i mieści się w zakresie 40–180 znaków.
• Progresywne ulepszanie: kotwica działa nadal, gdy skrypty, najechanie lub stylizacja podpowiedzi są niedostępne.
• Zachowanie klawiaturowe: focus jest widoczny; podpowiedź pojawia się przy focusie, może być zamknięta klawiszem Escape i nie zawiera elementów możliwych do focusowania.
• Zachowanie dotykowe: link ma normalny rozmiar celu i nie wymaga najechania ani niewyjaśnionej dwutapowej interakcji.
• Powściągliwość w danych strukturalnych: nie emitowano nieobsługiwanej relacji schematu ani wymyślonego typu elementu.
• Przenośny wynik: Markdown, Hugo i WordPress zachowują ten sam termin i kanoniczny href, nawet jeśli metadane podpowiedzi zostały pominięte.
• Status zrzutów ekranu: komentarze dotyczące przechwytywania pozostają niewyrenderowującymi instrukcjami, dopóki nazwane zasoby nie istnieją; nie ma odwołania do nieistniejącego obrazu.

FAQ

Szablon academy renderuje zweryfikowane pytania z frontmatteru dotyczące kwalifikowalności, pierwszego użycia, zakresu podpowiedzi, spójności kanonicznej i limitów linków.