Del via

Bruk koblinger i dokumentasjonen

  • Artikkel

Denne artikkelen beskriver hvordan du bruker hyperkoblinger fra sider som driftes på Microsoft Learn. Koblinger er enkle å legge til i markdown med noen få varierende konvensjoner. Koblinger viser brukere til innhold på samme side, på andre nabosider, eller på eksterne sider og URL-er.

Microsoft Learn-serverdel bruker Open Publishing Services (OPS), som støtter CommonMark-kompatibel Markdown analysert gjennom Markdig-analysemotoren. Denne Markdown-smaken er for det meste kompatibel med GitHub Flavored Markdown (GFM),ettersom de fleste dokumenter lagres i GitHub og kan redigeres der. Ekstra funksjonalitet legges til ved hjelp av Markdown-utvidelser.

Viktig

Alle koblinger må være sikre (https vs http) når målet støtter det.

Koble tekst

Ordene du inkluderer i koblingsteksten bør være vennlige. Med andre ord, bør de være normale engelske ord eller tittelen på siden som du kobler til.

Viktig

Ikke bruk «klikk her» som koblingstekst. Det er dårlig for optimalisering av søkemotor og beskriver ikke målet tilstrekkelig.

Rett:

  • For more information, see the [contributor guide index](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

  • For more details, see the [SET TRANSACTION ISOLATION LEVEL](/sql/t-sql/statements/set-transaction-isolation-level-transact-sql) reference.

Galt:

  • For more details, see [https://msdn.microsoft.com/library/ms173763.aspx](https://msdn.microsoft.com/library/ms173763.aspx).

  • For more information, click [here](https://github.com/Azure/azure-content/blob/master/contributor-guide/contributor-guide-index.md).

Koblinger fra en artikkel til en annen

Det finnes to typer hyperkoblinger som støttes av publiseringssystemet: URL-adresser og filkoblinger.

En URL-adressekobling kan være en URL-bane som er relativ til roten til https://learn.microsoft.com, eller en absolutt URL-adresse som inneholder den fullstendige URL-syntaksen (for eksempel https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Bruk URL-adresser når du kobler til innhold utenfor det gjeldende dokumentsettet, eller mellom autogenererte referanse- og begrepsmessige artikler i dokumentsettet.
  • Den enkleste måten å opprette en relativ kobling på er ved å kopiere URL-adressen fra nettleseren og deretter fjerne https://learn.microsoft.com/en-us fra verdien du limer inn i Markdown.
  • Ikke inkluder nasjonale innstillinger i URL-adresser for Microsoft-egenskaper (for eksempel fjern /en-us fra nettadressen).

En filkobling brukes til å lenke fra én artikkel til en annen i dokumentsettet.

  • Alle filbaner bruker skråstrektegn (/) i stedet for omvendt skråstrek.

  • En artikkel koblet til en annen artikkel i samme katalog:

    [link text](article-name.md)

  • En artikkel koblet til en artikkel i overordnet katalog til den gjeldende katalogen:

    [link text](../article-name.md)

  • En artikkel koblet til en artikkel i underordnet katalog til den gjeldende katalogen:

    [link text](directory/article-name.md)

  • En artikkel koblet til en artikkel i en underkatalog av overordnet katalog til den gjeldende katalogen:

    [link text](../directory/article-name.md)

  • Noen artikler består av både a .yml og .md fil, der .yml filen inneholder metadata og .md inneholder innholdet. I så fall kan du koble til .yml filen:

    [link text](../directory/article-name.yml)(ikke[link text](../directory/article-name-content.md))

Merk

Ingen av de foregående eksemplene bruker ~/ som del av koblingen. For å koble en absolutt bane som begynner ved roten av repositoriet, start med /. Hvis du inkluderer ~/, blir koblingene ugyldige når du navigerer i kilderepositorier i GitHub. Hvis du starter banen med /, fungerer koblingene som de skal.

Innhold publisert på Microsoft Learn har følgende url-struktur:

https://learn.microsoft.com/<locale>/<product-service>/[<feature-service>]/[<subfolder>]/<topic>[?view=<view-name>]

Eksempler:

https://learn.microsoft.com/azure/load-balancer/load-balancer-overview

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale> – identifiserer artikkelens soråk (eksempel: en-us eller de-de)
  • <product-service> – navnet på produktet eller tjenesten (eksempel: powershell, dotnet eller azure)
  • [<feature-service>] – (valgfritt) navnet på produktets funksjon eller tjeneste (eksempel: csharp eller belastningsfordeling)
  • [<subfolder>] – (valgfritt) navnet på en undermappe i en funksjon
  • <topic> – navnet på artikkelfilen for emnet (eksempel: belastningsfordelingsoversikt eller oversikt)
  • [?view=\<view-name>] – (valgfritt) visningsnavnet brukt av versjonsvelgeren for innholdet som har flere versjoner tilgjengelige (eksempel: azps-3.5.0)

Tips

I de fleste tilfeller har artikler i samme dokumentsett også samme <product-service>-URL-fragment. Eksempel:

  • Samme dokumentsett:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Forskjellig dokumentsett:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Hvis du vil koble en bokmerkekobling til en overskrift i den gjeldende filen, bruker du et hash-symbol, etterfulgt av ordene (i små bokstaver) i overskriften. Fjern tegnsetting fra overskriften og erstatt mellomrom med bindestreker:

[Managed Disks](#managed-disks)

Hvis du vil koble et bokmerke til en inndelingsoverskrift i en annen artikkel, kan du bruke file-relative- eller site-relative-koblingen samt et hash-symbol, etterfulgt av ordene i overskriften. Fjern tegnsetting fra overskriften og erstatt mellomrom med bindestreker:

[Managed Disks](../../linux/overview.md#managed-disks)

Du kan også kopiere bokmerkekoblingen fra URL-adressen. Hvis du vil finne nettadressen, holder du musepekeren over overskriftslinjen i Microsoft Learn. Det skal da vises et koblingsikon:

Koblingsikon på en artikkeloverskrift

Klikk på ikonet, og kopier deretter ankerteksten for bokmerket fra URL-adressen (den delen etter hashen).

Merk

Learn Markdown-utvidelsen har også verktøy for å opprette koblinger.

Det verken kreves eller anbefales at du legger til tydelige forankringskoblinger ved hjelp av HTML-taggen <a>, unntatt i huber og på målsider. I stedet kan du bruke de automatisk genererte bokmerkene som beskrevet i bokmerkekoblinger. Erklær forankringer for hub- og landingssider som følger:

## <a id="anchortext" />Header text

or

## <a name="anchortext" />Header text

Og følgende for å koble til ankeret:

To go to a section on the same page:
[text](#anchortext)

To go to a section on another page.
[text](filename.md#anchortext)

Merk

Ankerteksten må alltid være i små bokstaver, og kan ikke inneholde mellomrom.

XRef-koblinger er den anbefalte måten å koble til API-er på, fordi de gjør det enkelt å tilpasse koblingsteksten. I tillegg valideres de ved byggetidspunktet, og hvis URL-adressen til API-referansen skulle endres, vil koblingen fortsatt fungere. Hvis du vil koble til API-referansesider i det gjeldende dokumentsettet eller andre dokumentsett automatisk, bruker du XRef-koblinger med den unike ID-en (UID) fra typen eller medlemmet.

Tips

API Reference Link Helper-utvidelsen for VS Code gjør det super enkelt å sette inn .NET API Xref-koblinger i Markdown- og XML-filer.

Kontroller om API-en du vil koble til, er publisert på Microsoft Learn ved å skrive inn hele eller deler av det fullstendige navnet i søkeboksen .NET API eller Windows UWP . Hvis du ikke ser noen resultater som vises, er ikke typen ennå på Microsoft Learn.

Du kan bruke én av de følgende syntaksene:

  • Automatiske koblinger:

    <xref:UID>
<xref:UID?displayProperty=nameWithType>

    Koblingstekst viser bare medlems- og typenavnet, som standard. Den valgfrie spørringsparameteren displayProperty=nameWithType produserer fullstendig kvalifisert koblingstekst, det vil si namespace.type for typer, og type.member for typemedlemmer, deriblant opplistingstypemedlemmer.

  • Markdown-koblinger:

    [link text](xref:UID)

    Bruk Markdown-koblinger for XRef når du vil tilpasse koblingsteksten som vises.

Eksempler:

  • <xref:System.String> vises som String

  • <xref:System.String?displayProperty=nameWithType> vises som System.String

  • [Strengklasse] (xref:System.String) vises som strengklasse.

displayProperty=fullName-spørringsparameteren fungerer på samme som displayProperty=nameWithType gjør for klasser. Altså blir koblingsteksten namespace.classname. For medlemmer vises imidlertid koblingsteksten som namespace.classname.membername, som kan være uønsket.

Merk

I UID-er må det skilles mellom store og små bokstaver. Løser for eksempel <xref:System.Object> riktig, men <xref:system.object> ikke.

Fastslå UID-en

UID-en er vanligvis det fullstendig kvalifiserte klasse- eller medlemsnavnet. Hvis du vil finne UID-en, høyreklikker du på Microsoft Learn-siden for en type eller et medlem, velger Vis kilde og kopierer deretter innholdsverdien for ms.assetid.

ms.assetid i kilde for nettside

Prosentkoding av URL-adresser

Spesialtegn i UID må være prosentkodet på følgende måte:

Tegn HTML-koding
* *

Eksempel på koding:

  • System.Exception.#ctor kodes som System.Exception.%23ctor

Generiske typer

Generiske typer er typene som System.Collections.Generic.List<T>. Hvis du blar til denne typen i .NET API-nettleseren og ser på URL-adressen, vil du se at <T> er skrevet som -1 i URL-adressen, noe som faktisk representerer `1:

https://learn.microsoft.com/dotnet/api/system.collections.generic.list-1

Metoder

For å koble til en metode kan du enten koble til den generelle metodesiden ved å legge til en stjerne (*) etter metodenavnet, eller til en spesifikk overbelastning. Du kan for eksempel bruke generelt-siden når du vil koble til metoden <xref:System.Object.Equals*?displayProperty=nameWithType> uten spesifikke parametertyper. Eksempel:

<xref:System.Object.Equals*?displayProperty=nameWithType> kobler til Object.Equals

Hvis du vil koble til en bestemt overbelastning, kan du legge til parentes etter metodenavnet og inkludere det fullstendige typenavnet for hver parameter. Ikke bruk mellomrom mellom typenavnene. Hvis du gjør det, fungerer ikke koblingen. Eksempel:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> kobler til Object.Equals(Object, Object)

Fordi inkluderingsfiler er plassert i en annen katalog, må du bruke lengre relative baner. Hvis du vil koble til en artikkel fra en inkluderingsfil, kan du bruke dette formatet:

[link text](../articles/folder/article-name.md)

Tips

Utvidelsen Learn Authoring Pack for Visual Studio Code hjelper deg med å sette inn relative koblinger og bokmerker på riktig måte uten tedium for å finne ut baner.

En velger er en navigasjonskomponent som vises i en dokumentartikkel som en rullegardinliste. Når en leser velger en verdi i rullegardinlisten, åpner nettleseren den valgte artikkelen. Velgerlisten inneholder vanligvis koblinger til nært relaterte artikler, for eksempel samme tema på flere programmeringsspråk, eller et nært relatert utvalg artikler.

Hvis du har velgere som er bygd inn i en inkludering, bruker du denne koblingsstrukturen:

> [AZURE.SELECTOR-LIST (Dropdown1 | Dropdown2 )]
- [(Text1 | Example1 )](../articles/folder/article-name1.md)
- [(Text1 | Example2 )](../articles/folder/article-name2.md)
- [(Text2 | Example3 )](../articles/folder/article-name3.md)
- [(Text2 | Example4 )](../articles/folder/article-name4.md)

Du kan bruke referansestilkoblinger for å gjøre det enklere å lese kildeinnholdet. Referansestilkoblinger erstatter innebygd koblingssyntaks med forenklet syntaks som gjør det mulig å flytte lange URL-adresser til slutten av artikkelen. Her er Daring Fireballs eksempel:

Innebygd tekst:

I get 10 times more traffic from [Google][1] than from [Yahoo][2] or [MSN][3].

Koblingsreferanser på slutten av artikkelen:

<!--Reference links in article-->
[1]: http://google.com/
[2]: http://search.yahoo.com/
[3]: http://search.msn.com/

Kontroller at du inkluderer mellomrommet etter kolonet, før koblingen. Når du kobler til andre tekniske artikler og glemmer å inkludere mellomrommet, brytes koblingen i en publisert artikkel.

Hvis du vil koble til en side på en annen Microsoft-eiendom (for eksempel en prisside, SLA-side, eller noe annet som ikke er en dokumentasjons-artikkel), bruker en absolutt URL-adresse, men utelater den nasjonale innstillingen. Målet her er at koblinger fungerer i GitHub og i det gjengitte området:

[link text](https://azure.microsoft.com/pricing/details/virtual-machines/)

Man skaper den beste brukeropplevelsen ved å sende brukere til et annet område så sjeldent som mulig. Baser koblinger til tredjepartssider, som vi noen ganger trenger, på denne informasjonen:

  • Ansvarlighet: Koble til tredjepartsinnhold når det er tredjepartens informasjon som skal deles. Det er for eksempel ikke opp til Microsoft å fortelle andre hvordan de skal bruke utviklerverktøy for Android – det er opp til Google. Hvis vi må, kan vi forklare hvordan du bruker Android-utviklerverktøy med Azure, men Google bør fortelle historien om hvordan du bruker verktøyene deres.
  • PM-godkjenning: Be om at Microsoft godkjenner tredjepartsinnhold. Ved å koble til noe, sier vi noe om vår tillit til dette, og vår forpliktelse hvis folk følger instruksjonene.
  • Nyhetsvurderinger: Kontroller at tredjepartsinformasjonen fortsatt er oppdatert, korrekt og relevant, og at koblingen ikke er endret.
  • Frakoblet: Gjør brukere oppmerksom på at de kommer til et annet område. Hvis konteksten ikke gjør det klart, kan du legge til et kvalifiserende uttrykk. For eksempel: «Forutsetninger inkluderer Android Developer Tools, som du kan laste ned på Android Studio-nettstedet.»
  • Neste trinn: Det er greit å legge til en kobling til for eksempel en MVP-blogg i en «Neste trinn»-inndeling. Bare sørg for at brukere forstår at de forlater området.
  • Juridisk: Vi dekkes lovlig under Koblinger til tredjepartsnettsteder i bunnteksten for bruk på hver microsoft.com side.