Glossarlenker og verktøytips: Skriveregler

En glossarlenke forbinder et begrep ved første meningsfulle omtale med den ene siden som eier den fullstendige definisjonen. Lenken hjelper leseren med å forstå ukjent språk uten å avbryte artikkelen, og den gir søkemotorer en konsistent relasjon mellom begrepet og dets kanoniske entitetsside.

En kanonisk URL er den foretrukne versjonen av en side når flere URL-er inneholder samme eller vesentlig likt innhold.

Den setningen er selve elementet. Ankeret er det eksakte begrepet, destinasjonen er den kanoniske glossaroppføringen, og den omkringliggende setningen forblir forståelig uten å åpne lenken. På systemer som støtter det, kan samme lenke vise et kort definisjonsverktøytips ved sveving eller tastaturfokus. Den lenkede siden – ikke verktøytipset – forblir sannhetskilden.

Hvorfor dette elementet er viktig

Lesere kommer ikke med samme vokabular. En spesialist kjenner kanskje igjen «kanonisk URL» umiddelbart, mens en kjøper eller et nytt teammedlem kan trenge en definisjon. Å forklare hvert begrep i parentes bremser prosa for eksperter; å forklare ingen utelukker nykommere. En glossarlenke skaper en stille nødutgang: fortsett hvis begrepet er kjent, eller åpne definisjonen hvis det ikke er det.

Førsteomtaleregelen er viktig fordi usikkerhet forsterkes. Hvis en leser misforstår et begrep i andre avsnitt, blir alle senere påstander bygget på det begrepet vanskeligere å vurdere. Å lenke den første meningsfulle forekomsten løser usikkerheten før den sprer seg. Regelen betyr ikke «lenk den første strengen som matcher». Et begrep i en tittel, navigasjonsetikett, kodeeksempel eller teaser bærer kanskje ikke den betydningen som brukes i forklaringen.

Maskinuttrekkbarhet er evnen programvare har til å bevare en relasjon etter at presentasjonen er fjernet. Et beskrivende anker og en stabil destinasjon skaper en eksplisitt kant: denne siden bruker begrepet, og den glossarsiden definerer det. Konsekvente kanter forsterker hvilken URL som eier definisjonen. De skaper ikke en formell kunnskapsgraf eller garanterer synlighet, men de reduserer tvetydighet som en søkemotor ellers ville måtte løse kun ut fra nærhet.

Over-lenking reverserer disse fordelene. Når hvert gjentatte begrep lenkes, slutter siden å signalisere prioritet. Lesere møter et felt av konkurrerende utganger, brukere av hjelpeteknologi hører samme destinasjon gjentatte ganger, og maskiner mottar mange overflødige kanter i stedet for et lite sett med bevisste relasjoner. Én kanonisk lenke ved første meningsfulle omtale er derfor standarden, ikke et minimum å gjenta i hver seksjon.

Når du skal bruke det

Bruk elementet når alle tre betingelsene er oppfylt:

1. Begrepet har en kanonisk glossarside, snarere enn flere tilnærmet like definisjoner.
2. Å forstå begrepet hjelper leseren vesentlig med å forstå den aktuelle siden.
3. Den første meningsfulle bruken kan bære et beskrivende anker uten å forvrenge setningen.

Gode kandidater inkluderer fagterminologi, akronymer ved første utvidede bruk, navngitte standarder, måleverdier og ord hvis faglige betydning skiller seg fra dagligspråket. Et verktøytips kan forhåndsvise én kort definisjon; den fullstendige glossarsiden håndterer grenser, eksempler, kilder og relaterte begreper.

Nære bommerter er der elementet oftest misbrukes:

• Vanlig vokabular: ikke lenk et kjent ord bare fordi en glossaroppføring finnes.
• Tilfeldige omtaler: hvis artikkelen nevner et begrep men ikke bygger på det, skaper en lenke en unødvendig utgang.
• Gjentatte omtaler: etter første lenkede bruk, la begrepet stå som tekst, med mindre en lang, flerdelt side skaper en genuint uavhengig lesekontekst.
• Tvetydig ankertekst: «denne tilnærmingen», «les mer» og «måleverdien» identifiserer ikke glossarentiteten. Lenk selve begrepet.
• Ingen kanonisk destinasjon: ikke erstatt med et søkeresultat, tag-arkiv eller løst relatert artikkel. Bruk vanlig prosa inntil den kanoniske definisjonen finnes.
• Definisjon allerede gitt i sin helhet: hvis glossaret ikke tilfører nyttig dybde, kan en ekstra definisjonsavstikker være unødvendig.
• Kommersiell omdirigering: en glossarlenke er ikke en forkledd produkt-handlingsknapp. Produktsider, påmeldingsflyter og prissider tjener andre leserintensjoner.

Bruk de felles element-skrivereglene før du improviserer. Deres forrangsregel krever at forfattere velger et element basert på formål. Hvis formålet er å knytte et navngitt begrep til dets kanoniske definisjon, bruk denne typede relasjonen fremfor en generisk lenke i teksten som er stilet til å se lik ut.

Hvor du skal plassere det

Plasser lenken på første meningsfulle prosaiske omtale: den første setningen som bruker begrepet i destinasjonens betydning. Hvis begrepet først vises i tittelen eller en H2, lenk den første bruken i det påfølgende avsnittet. Overskrifter bør forbli stabile seksjonsetiketter snarere enn store navigasjonsmål.

For et akronym, skriv fullt begrep etterfulgt av forkortelsen og lenk fullt begrep: retrieval-augmented generation (RAG). Senere forekomster kan bruke RAG uten lenke.

Ikke plasser en glossarlenke:

• inni en annen lenke, knapp eller klikkbart kort;
• ved siden av en andre lenke på samme ankertekst;
• i kode, en URL, en e-postadresse eller bokstavelig brukerentrert tekst;
• i en overskrift utelukkende for å oppfylle førsteomtaleregelen;
• i hver rad i en tabell når én lenket definisjon i innledningen kan etablere begrepet;
• rett ved siden av en siteringsmarkør hvis de to målene blir visuelt eller operativt uatskillelige;
• inni en verktøytipsutløser som er separat fra selve lenken.

Hvis en setning inneholder flere ukjente begreper, lenk kun de begrepene som trengs for å forstå setningen. Tre eller flere glossarlenker i én setning er et varsel om at prosaen antar for mye vokabular. Omskriv setningen, definer ett begrep på stedet, eller del opp forklaringen før du legger til flere utganger.

Anatomi

Det merkede eksemplaret har seks områder:

1. Begrepsanker: det synlige begrepet eller fullstendige utvidede navnet, uten «les mer».
2. Kanonisk destinasjon: én stabil glossar-URL som eier definisjonen.
3. Kontekstsetning: nok prosa til å forstå hvorfor begrepet vises, selv om lenken ikke åpnes.
4. Lenkestil: nettstedets standard innebygde lenkebehandling; farge er ikke det eneste signalet.
5. Fokusindikator: en synlig tastaturtilstand som ikke er beskåret av avsnittet eller verktøytipset.
6. Valgfritt verktøytips: en kort forhåndsvisning knyttet til selve lenken, aldri en separat ikon-basert kontroll.

Presentasjonen kan endres uten å endre ankeret, destinasjonen eller førsteomtaleatferden.

Designeksempler

Hver variant bevarer den samme semantiske lenken.

Standard innebygd lenke: det påkrevde grunnnivået. Det fungerer med JavaScript deaktivert, i lesemodus, i utskriftsannotasjoner og på enheter uten sveving.

Definisjonsverktøytips ved fokus eller sveving: en forbedring for tett pedagogisk innhold. Forhåndsvisningen er én eller to setninger og inneholder aldri lenker, knapper, siteringer eller formateringskontroller.

Mobil og berøring: det første trykket følger lenken med mindre produktet har et etablert, tilgjengelig utvidelsesmønster. Ikke tving brukere til å oppdage at ett trykk åpner en forhåndsvisning og et andre trykk navigerer, med mindre den interaksjonen er konsistent på tvers av nettstedet og tydelig kommunisert.

Mørk bakgrunn: lenke, fokusring, verktøytipstekst og verktøytipsgrense beholder tydelig kontrast. Ikke fjern understrekingen bare fordi aksentfargen er lys.

Parametere

Den kanoniske URL-en og det synlige ankeret er innholdsbeslutninger. Verktøytipsatferd tilhører gjengiveren. Å skille disse kildene forhindrer at en valgfri grensesnittfunksjon endrer betydningen av lenken.

Utled aldri href fra term: homonymer kan dele stavemåte men kreve ulike destinasjoner. Hent et verktøytips fra glossaroppføringen bare når dens korte definisjon er gjennomgått for bruk utenfor siden.

Syntaks og kodeeksempler

Alle tre formatene bevarer en normal lenke som kjerne. De navngitte feltene er en bærbar kontrakt; en plattform kan gjengi dem med en opprinnelig blokk, utvidelse eller forbehandlingstrinn.

Bærbar Markdown-direktiv

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.

Hvis publiseringspipelinen ikke støtter innebygde direktiver, bruk vanlig Markdown og utelat verktøytipset:

The [canonical URL](/glossary/canonical-url/) consolidates signals on the preferred page.

Hugo shortkode

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.

Denne notasjonen spesifiserer den nødvendige mappingen; den krever ikke at forfattere innfører en ny shortkode i et prosjekt som allerede håndterer glossarlenker gjennom Markdown-gjengivelse eller innholdsforbehandling. Det gjengitte faltilfellet må alltid være et vanlig <a href>-element.

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

Eksportert innhold må beholde ankeret og href selv når verktøytipsmetadata ikke er tilgjengelig.

Eksempler

Bra

Velg én kanonisk URL for vesentlig like sider slik at indekseringssignaler peker til den foretrukne versjonen.

I den gjengitte artikkelen lenker «kanonisk URL» til /glossary/canonical-url/ ved denne første meningsfulle bruken. Ankeret navngir entiteten nøyaktig, setningen gir nok lokal kontekst til å fortsette å lese, og senere forekomster forblir ren tekst. En leser kan velge om den fulle definisjonen er nødvendig.

Dårlig

Velg én foretrukket side for lignende sider. Din kanoniske URL bør deretter referere til den kanoniske URL-en i hver seksjon.

Dette mislykkes på to måter. «Foretrukket side» er beslektet ordlyd, men ikke det eksakte begrepet destinasjonen definerer, så relasjonen er mindre eksplisitt. Å gjenta den kanoniske URL-lenken i hver seksjon legger til utganger uten å tilføre mening. Den korrekte løsningen er å lenke «kanonisk URL» én gang ved første meningsfulle bruk og la senere bruk forbli uten lenke.

Et annet dårlig mønster er et informasjonsikon etter et ulenket begrep. Ikonet skjuler destinasjonen for lesere som skanner lenketekst, skaper et lite trykkmål, og kan skille verktøytipset fra den navigerbare glossarrelasjonen.

Skjemamarkering og tilgjengelighet

En glossarlenke trenger ingen frittstående Schema.org-type. Den forblir en lenke inni den omsluttende Article, TechArticle eller WebPage. Ikke konstruer DefinedTerm, mentions eller about-markering for hver innebygde lenke; legg til slike relasjoner kun gjennom en konsistent datamodell på sidenivå som er rettferdiggjort av synlig innhold.

Tilgjengelighet starter med et ekte anker. Det må være forståelig i kontekst, skillbart uten farge alene, tastaturnåbart og synlig fokusert. Viktig informasjon kan ikke kun finnes i verktøytipset.

Hvis et verktøytips implementeres, knytt det til ankeret ved hjelp av aria-describedby mens det er synlig. Åpne det ved tastaturfokus så vel som pekersveving, hold det åpent mens pekeren beveger seg over verktøytipset, og la Escape avvise det uten å flytte fokus. Ikke plasser fokuserbare kontroller inne i et verktøytips. Ikke stol på HTML-attributtet title som definisjonsgrensesnitt: tidsinnstilling, presentasjon, berøringsstøtte og eksponering for hjelpeteknologi er inkonsistente. Et title kan være tilleggsinformasjon, men det er ikke det tilgjengelige navnet, beskrivelsen eller den kanoniske definisjonen.

Lenken må navigere når skript feiler. På berøringsenheter, foretrekk direkte navigering fremfor svevingsimitasjon. Hvis forbedringen ikke kan oppfylle disse kravene, lever den rene lenken.

Skriveregler

Lenk det eksakte begrepet eller dets utvetydige fulle form. Hold ankere på én til åtte ord og under 80 tegn. Inkluder artikler som «en» eller «et» bare når de er del av et egennavn. Ikke uthev hvert glossaranker med fet skrift; standard lenkestil kommuniserer allerede interaktivitet, og stablet vektlegging gjør teknisk prosa støyende.

Bruk én glossarlenke per begrep per side som standard. En andre lenke er akseptabel bare når uavhengig konsumert innhold – som et langt vedlegg, frittstående FAQ-svar eller innebygd modul – ellers ville miste relasjonen. Ikke sett et fast minimumsantall glossarlenker. En tydelig side med to nødvendige begreper er bedre enn en side med ti dekorative utganger.

Verktøytipsdefinisjoner bør være 40–180 tegn og ikke mer enn to setninger. Si hva begrepet er, ikke hvorfor leseren bør klikke. Bruk nøytral, deklarativt språk. Forhåndsvisningen må stemme overens med destinasjonens gjeldende definisjon og bør hentes fra glossaroppføringen når mulig, slik at oppdateringer ikke avviker.

Sett aldri disse inne i lenken eller verktøytipset:

• en annen lenke, knapp, skjemakontroll eller interaktivt ikon;
• en salgspåstand eller handlingsknapp;
• en siteringsliste eller kildehenvisning;
• et bilde, video, tabell, kodeblokk eller flertrinnsprosedyre;
• en definisjon som er i konflikt med eller utvider den kanoniske siden;
• instruksjoner som er essensielle for å fullføre leserens oppgave.

Gå gjennom homonymer manuelt. «Java», «konvertering» eller «agent» kan navngi ulike entiteter. Setningen og destinasjonen må løse samme betydning. Roter aldri destinasjoner for lenkedistribusjon; kanonisitet er poenget.

Innleggstyper som bruker det

Front matter-feltet postTypes[] identifiserer formatene som dette elementet er en dokumentert del av innholdssystemet for. Tabellen angir hvordan hvert format anvender den samme førsteomtalekontrakten.

QA-sjekkliste

• Kanonisk destinasjon: stien er den ene glossarsiden som eier definisjonen; den er ikke en søke-, tagg-, produkt- eller relatert-artikkel-URL.
• Destinasjonen finnes: innholdsfilen finnes nå eller stien vises i det godkjente kanoniske registeret for samme utgivelse.
• Betydning samsvarer: ankeret og destinasjonen refererer til samme betydning av begrepet, inkludert tvetydige akronymer og homonymer.
• Første meningsfulle omtale: lenken vises i prosa før senere bruk, ikke i en overskrift eller kodeeksempel bare fordi den forekomsten kom først i kildekode-rekkefølge.
• Eksakt anker: de lenkede ordene navngir begrepet eller dets utvetydige fulle form; det er ingen «klikk her» eller vag erstatning.
• Lokal setning fungerer: en leser kan forstå setningen uten å åpne destinasjonen eller utløse verktøytipset.
• Ett-per-begrep standard: gjentatte forekomster forblir ulenkede med mindre en dokumentert uavhengig lesekontekst rettferdiggjør en annen lenke.
• Ingen lenkeklynge: setningen og avsnittet forblir lesbare; overdrevent mange ukjente begreper omskrives snarere enn dekkes med lenker.
• Verktøytipsparitet: eventuell forhåndsvisning samsvarer med den kanoniske definisjonen og holder seg innenfor 40–180 tegn.
• Progressiv forbedring: ankeret fungerer fortsatt når skript, sveving eller verktøytipsstil ikke er tilgjengelig.
• Tastaturoppførsel: fokus er synlig; verktøytipset vises ved fokus, kan avvises med Escape, og inneholder ingen fokuserbare kontroller.
• Berøringsoppførsel: lenken har normal målstørrelse og krever ikke sveving eller en uforklarlig totrykksinteraksjon.
• Strukturert-data-begrensning: ingen ustøttet skjemarelasjon eller oppfunnet elementtype utstedes.
• Bærbart output: Markdown, Hugo og WordPress bevarer samme begrep og kanoniske href selv om verktøytipsmetadata droppes.
• Skjermbildestatus: fangkommentarer forblir ikke-gjengivende instruksjoner inntil de navngitte ressursene finnes; ikke-eksisterende bilde refereres ikke.

FAQ

Academy-malen gjengir de gjennomgåtte spørsmålene fra front matter som dekker kvalifisering, første omtale, verktøytipsomfang, kanonisk konsistens og lenkebegrensninger.