Del via

Anvend links i dokumentation

  • Artikel

I denne artikel beskrives det, hvordan du bruger links fra sider, der hostes i Microsoft Learn. Det er nemt at tilføje links i Markdown med et par forskellige konventioner. Links dirigerer brugere til indhold på den samme side, på tilstødende sider eller på eksterne websteder og URL-adresser.

Microsoft Learn-backend bruger OPS (Open Publishing Services), som understøtter CommonMark-kompatibel Markdown, der fortolkes via Markdig-fortolkningsprogrammet . Denne Markdown-variant er for det meste kompatibel med GFM (GitHub Flavored Markdown), da de fleste dokumenter er gemt i GitHub og kan redigeres der. Yderligere funktioner tilføjes via Markdown-udvidelser.

Vigtigt

Alle links skal være sikre (https vs http), når destinationen understøtter det.

Linktekst

Brug letforståelige ord i din linktekst. Det skal med andre ord være almindelige engelske ord eller titlen på den side, du opretter et link til.

Vigtigt

Brug ikke "klik her" som linktekst. Det er dårligt for optimering af søgemaskiner, og det er ikke en relevant beskrivelse af destinationen.

Korrekt:

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

Forkert:

  • 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).

Links mellem artikler

Der er to typer links, der understøttes af udgivelsessystemet: URL-adresser og fillinks.

Et URL-link kan være en URL-sti, der er relativ i forhold til roden af https://learn.microsoft.com, eller en absolut URL-adresse, der indeholder hele URL-syntaksen (f.eks. https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Brug links til URL-adresser, når du linker til indhold uden for det aktuelle dokumentsæt eller mellem de automatisk genererede reference- og konceptartikler i dokumentsættet.
  • Den nemmeste måde at oprette et relativt link på er ved at kopiere URL-adressen fra din browser og derefter fjerne https://learn.microsoft.com/en-us fra den værdi, du indsætter i Markdown.
  • Medtag ikke landestandarder i URL-adresser til Microsoft-egenskaber (f.eks. fjern /en-us fra URL-adressen).

Et fillink bruges til at linke fra én artikel til en anden i dokumentsættet.

  • Der bruges skråstreg (/) i alle filstier i stedet for omvendte skråstreger.

  • En artikel linker til en anden artikel i den samme mappe:

    [link text](article-name.md)

  • En artikel linker til en artikel i den overordnede mappe for den aktuelle mappe:

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

  • En artikel linker til en artikel i en underordnet mappe for den aktuelle mappe:

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

  • En artikel linker til en artikel i en underordnet mappe for den overordnede mappe for den aktuelle mappe:

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

  • Nogle artikler består af både en .yml og .md -fil, hvor .yml filen indeholder metadata og .md indeholder indholdet. I så fald skal du linke .yml til filen:

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

Bemærk

Ingen af de tidligere eksempler bruger ~/ som en del af linket. Hvis du vil linke til en absolut sti, der begynder i lagerets rod, skal du indlede linket med /. Hvis du inkluderer ~/, giver det ugyldige links, når du navigerer til kildelagrene på GitHub. Hvis du starter stien med /, gengives det korrekt.

Indhold, der er publiceret 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> – angiver sproget i artiklen (f.eks. en-us eller de-de)
  • <product-service> – navnet på produktet eller tjenesten (f.eks. powershell, dotnet eller azure)
  • [<feature-service>] – (valgfrit) navnet på produktets funktion eller undertjeneste (f.eks. csharp eller load-balancer)
  • [<subfolder>] – (valgfrit) navnet på en undermappe i en funktion
  • <topic> – navnet på artikelfilen for emnet (f.eks. load-balancer-overview eller overview)
  • [?view=\<view-name>] – (valgfrit) det viste navn, der bruges af versionsvælgeren til indhold, som har flere tilgængelige versioner (f.eks. azps-3.5.0)

Tip

I de fleste tilfælde har artikler i det samme dokumentsæt det samme fragment af URL-adressen <product-service>. Eksempler:

  • Samme dokumentsæt:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Andet dokumentsæt:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Hvis du vil angive bogmærkelinks til en overskrift i den aktuelle fil, skal du bruge et hashtag efterfulgt af overskriftsteksten med små bogstaver. Fjern tegnsætning fra overskriften, og erstat mellemrum med tankestreger:

[Managed Disks](#managed-disks)

Hvis du vil linke til et bogmærke i en overskrift i en anden artikel, skal du enten bruge linket, der er relativt til filen, eller linket, der er relativt til webstedet, plus et hashtag efterfulgt af overskriftsteksten. Fjern tegnsætning fra overskriften, og erstat mellemrum med tankestreger:

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

Du kan også kopiere bogmærkelinket fra URL-adressen. Hvis du vil finde URL-adressen, skal du holde musen over overskriftslinjen i Microsoft Learn. Et linkikon bør blive vist:

Linkikon i artikeloverskrift

Klik på linkikonet, og kopiér derefter ankerteksten i bogmærket fra URL-adressen (dvs. delen efter hashtagget).

Bemærk

Udvidelsen Learn Markdown indeholder også værktøjer, der kan hjælpe med at oprette links.

Tilføjelse af eksplicitte ankerlinks ved hjælp af HTML-tags for <a> kræves ikke og anbefales heller ikke bortset fra i hubben og på landingssider. Brug i stedet de automatisk genererede bogmærker, som beskrevet under bogmærkelinks. Angiv ankre for hubben og landingssider på følgende måde:

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

or

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

Og følgende for at linke 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)

Bemærk

Ankertekst skal altid være med små bogstaver og må ikke indeholde mellemrum.

XRef-links er den anbefalede måde at linke til API'er på, da de gør det nemt at tilpasse linkteksten. Derudover valideres de på oprettelsestidspunktet, og hvis URL-adressen til API-referencen ændres, fungerer linket stadig. Hvis du vil linke til automatisk genererede API-referencesider i det aktuelle dokumentsæt eller andre dokumentsæt, skal du bruge XRef-links med det entydige ID (UID) for typen eller medlemmet.

Tip

Udvidelsen API Reference Link Helper til VS Code gør det super nemt at indsætte .NET API Xref-links i Markdown- og XML-filer.

Kontrollér, om den API, du vil oprette et link til, er publiceret i Microsoft Learn ved at skrive hele eller noget af dens fulde navn i .NET API-browseren eller Windows UWP-søgefeltet. Hvis du ikke kan se nogen resultater, der vises, er typen endnu ikke på Microsoft Learn.

Du kan bruge en af følgende syntakser:

  • Automatiske links:

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

    I linkteksten vises som standard kun medlems- eller typenavnet. Den valgfrie forespørgselsparameter displayProperty=nameWithType producerer fuldt kvalificeret linktekst, dvs. namespace.type for typer og type.member for typemedlemmer, herunder medlemmer af optællingstypen.

  • Links af Markdown-typen:

    [link text](xref:UID)

    Brug links af Markdown-typen til XRef, når du vil tilpasse den linktekst, der vises.

Eksempler:

  • <xref:System.String> vises som String

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

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

Forespørgselsparameteren displayProperty=fullName fungerer på samme måde som displayProperty=nameWithType for klasser. Det vil sige, at linkteksten bliver namespace.classname. For medlemmer vises linkteksten dog som namespace.classname.membername, hvilket kan være uønsket.

Bemærk

Der skelnes mellem store og små bogstaver i UID'er. Løses f.eks <xref:System.Object> . korrekt, men <xref:system.object> gør det ikke.

Fastslå UID

UID er normalt det fuldt kvalificerede navn på klassen eller medlemmet. Hvis du vil bestemme UID'et, skal du højreklikke på siden Microsoft Learn for en type eller et medlem, vælge Vis kilde og derefter kopiere indholdsværdien for ms.assetid.

ms.assetid i kilde for webside

Procentkodning af URL-adresser

Specialtegn i UID'et skal være procentkodet på følgende måde:

Tegn HTML-kodning
* *

Kodningseksempel:

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

Generiske typer

Generiske typer er typer som f.eks. System.Collections.Generic.List<T>. Hvis du navigerer til denne type i .NET API-browseren og kigger på dens URL-adresse, kan du se, at <T> er skrevet som -1 i URL-adressen, hvilket faktisk repræsenterer `1:

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

Metoder

Hvis du vil linke til en metode, kan du enten linke til den generelle metodeside ved at tilføje en stjerne (*) efter navnet på metoden eller til en specifik overbelastning. Du kan f.eks. bruge den generelle side, når du vil linke til metoden <xref:System.Object.Equals*?displayProperty=nameWithType> uden specifikke parametertyper. Eksempler:

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

Hvis du vil linke til en specifik overbelastning, skal du tilføje parentes efter navnet på metoden og inkludere det fulde typenavn for hver parameter. Angiv ikke mellemrum mellem typenavnene, for så fungerer linket ikke. Eksempler:

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

"Include"-filer placeres i en anden mappe, så du skal bruge længere relative stier. Hvis du vil oprette et link til en "include"-fil, skal du bruge dette format:

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

Tip

Udvidelsen Learn Authoring Pack til Visual Studio Code hjælper dig med at indsætte relative links og bogmærker korrekt uden at skulle finde stier.

En selektor er en navigationskomponent, der vises i en dokumentationsartikel som en rulleliste. Når en læser vælger en værdi på rullelisten, åbnes den valgte artikel i browseren. Selektorlisten indeholder som regel links til nært beslægtede artikler, f.eks. det samme emne i flere programmeringssprog eller en række relaterede artikler.

Hvis du har selektorer, som er integreret i en "include"-fil, skal du bruge følgende linkstruktur:

> [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 bruge referencelinks til at gøre dit kildeindhold mere læsevenligt. Referencelinks forenkler syntaksen for indbyggede links ved at flytte lange URL-adresser til slutningen af artiklen. Her er et eksempel fra Daring Fireball:

Indbygget tekst:

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

Linkreferencer i slutningen af artiklen:

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

Husk at medtage et mellemrum efter kolonet før linket. Hvis du glemmer mellemrummet, når du opretter et link til andre tekniske artikler, virker linket ikke i den udgivne artikel.

Hvis du vil oprette et link til en anden Microsoft-hjemmeside (f.eks. en side med priser, en SLA-side eller andre sider, som ikke er dokumentationsartikler), skal du bruge en absolut URL-adresse, men udelade landestandarden. Målet her er, at links skal virke både i GitHub og på det websted, hvor de gengives:

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

Du opnår den bedste brugeroplevelse ved at minimere brugen af links, som sender brugere til et andet websted. Links til påkrævede tredjepartsoplysninger bør derfor baseres på:

  • Ansvarlighed: Opret kun links til indhold fra tredjepart, som faktisk bør dele disse oplysninger. Det er f.eks. ikke Microsofts opgave at fortælle andre, hvordan de skal bruge Android Developer Tools – det er Googles opgave. Vi kan fortælle, hvordan man bruger Android Developer Tools med Azure, men det er Googles opgave at fortælle, hvordan man bruger deres værktøjer.
  • PM-godkendelse: Anmod Microsoft om at godkende tredjepartsindhold. Når vi opretter links til indhold, siger vi noget om vores tillid til indholdet og vores forpligtelser, hvis personerne følger instrukserne.
  • Anmeldelser af friskhed: Sørg for, at tredjepartsoplysningerne stadig er aktuelle, korrekte og relevante, og at linket ikke er blevet ændret.
  • Offsite: Gør brugerne opmærksom på, at de bliver taget til et andet websted. Tilføj et kvalificerende udtryk, hvis det ikke fremgår tydeligt af konteksten. For eksempel: "Forudsætninger omfatter Android Developer Tools, som du kan downloade på Android Studio-webstedet."
  • Næste trin: Det er fint at tilføje et link til f.eks. en MVP-blog i afsnittet "Næste trin". Du skal bare huske at gøre brugerne opmærksomme på, at de forlader webstedet.
  • Juridisk: Vi er juridisk dækket under Links til tredjepartswebsteder i sidefoden vilkår for anvendelse på hver microsoft.com side.