Delen via

Koppelingen in documentatie gebruiken

  • Artikel

In dit artikel wordt beschreven hoe u hyperlinks gebruikt van pagina's die worden gehost op Microsoft Learn. Koppelingen kunnen eenvoudig in Markdown worden toegevoegd, met een aantal afwijkende conventies. Koppelingen verwijzen gebruikers naar inhoud op dezelfde pagina, op omliggende pagina's of op externe websites en URL's.

De Microsoft Learn-back-end maakt gebruik van Open Publishing Services (OPS), die ondersteuning biedt voor Markdown die compatibel is met CommonMark, geparseerd via de Markdig-parsing-engine . Deze Markdown-smaak is voornamelijk compatibel met GitHub Flavored Markdown (GFM), omdat de meeste documenten worden opgeslagen in GitHub en daar kunnen worden bewerkt. Er wordt aanvullende functionaliteit toegevoegd met Markdown-extensies.

Belangrijk

Alle koppelingen moeten veilig (https vs http) zijn wanneer het doel dit ondersteunt.

Tekst van koppeling

De woorden die u gebruikt in de tekst van de koppeling moeten duidelijk de bestemming van de koppeling aangeven. Gebruik dus normale beschrijvende tekst of de titel van de pagina die u wilt koppelen.

Belangrijk

Gebruik 'klik hier' niet als koppelingstekst. Het is nadelig voor de zoekmachineoptimalisatie en geeft geen goede beschrijving van het doelobject.

Juist:

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

Onjuist:

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

Koppelingen van het ene artikel naar het andere

Er worden twee typen hyperlinks ondersteund door het publicatiesysteem: URL's en bestandskoppelingen.

Een URL-koppeling kan een URL-pad zijn dat relatief is ten opzichte van de hoofdmap van https://learn.microsoft.com, of een absolute URL die de volledige URL-syntaxis bevat (bijvoorbeeld https://github.com/MicrosoftDocs/PowerShell-Docs).

  • Gebruik URL-koppelingen wanneer u een koppeling maakt naar inhoud buiten de huidige docset of tussen automatisch gegenereerde naslaginformatie en conceptuele artikelen in de docset.
  • De eenvoudigste manier om een relatieve koppeling te maken, is door de URL te kopiëren uit uw browser en vervolgens https://learn.microsoft.com/en-us te verwijderen uit de waarde die u in Markdown hebt geplakt.
  • Neem geen landinstellingen op in URL's voor Microsoft-eigenschappen (bijvoorbeeld verwijderen /en-us uit de URL).

Een bestandskoppeling wordt gebruikt om een koppeling te maken van het ene naar het andere artikel binnen de docset.

  • Alle bestandspaden gebruiken tekens die gebruikmaken van slash- (/) in plaats van backslash-tekens.

  • Een artikel wordt gekoppeld aan een ander artikel in dezelfde map:

    [link text](article-name.md)

  • Een artikel wordt gekoppeld aan een artikel in de bovenliggende map van de huidige map:

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

  • Een artikel wordt gekoppeld aan een artikel in een submap van de huidige map:

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

  • Een artikel wordt gekoppeld aan een artikel in een submap van de bovenliggende map van de huidige map:

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

  • Sommige artikelen bestaan uit zowel een als .md een .yml bestand, waarbij het .yml bestand metagegevens bevat en de .md inhoud bevat. In dat geval maakt u een koppeling naar het .yml bestand:

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

Notitie

Geen van de eerder genoemde voorbeelden gebruikt de ~/ als onderdeel van de koppeling. Als u een koppeling wilt maken naar een absoluut pad dat bij de hoofdmap van de opslagplaats begint, begint u de koppeling met /. Als u de ~/ opneemt, worden de koppelingen ongeldig als er wordt verwezen naar bronopslagplaatsen in GitHub. Als u het pad begint met /, wordt het correct omgezet.

Inhoud die is gepubliceerd op Microsoft Learn heeft de volgende URL-structuur:

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

Voorbeelden:

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

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1
  • <locale> -geeft de taal van het artikel weer (bijvoorbeeld: en-us of nl-nl)
  • <product-service> -de naam van het product of de service (bijvoorbeeld: powershell, dotnet, of azure)
  • [<feature-service>] -(optioneel) de naam van de functie of subservice van het product (bijvoorbeeld: csharp of load balancer)
  • [<subfolder>] -(optioneel) de naam van een submap binnen een functie
  • <topic> -de naam van het artikelbestand voor het onderwerp (bijvoorbeeld: load balancer-overzicht of overzicht)
  • [?view=\<view-name>] -(optioneel) de weergavenaam die wordt gebruikt door de versieselector voor inhoud met meerdere beschikbare versies (bijvoorbeeld: azps-3.5.0)

Tip

Artikelen in dezelfde docset bevatten in de meeste gevallen hetzelfde URL-fragment <product-service>. Voorbeeld:

  • Dezelfde docset:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/dotnet/framework/install
  • Verschillende docset:
    • https://learn.microsoft.com/dotnet/core/get-started
    • https://learn.microsoft.com/visualstudio/whats-new

Als u een bladwijzerkoppeling wilt maken naar een kop in het huidige bestand, gebruikt u een hash-symbool gevolgd door de kop in kleine letters. Verwijder leestekens uit de kop en vervang spaties door streepjes:

[Managed Disks](#managed-disks)

Als u wilt koppelen naar een bladwijzerkop in een ander artikel, gebruikt u de koppeling ten opzichte van het bestand of de site plus een hash-symbool, gevolgd door de woorden van de kop. Verwijder leestekens uit de kop en vervang spaties door streepjes:

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

U kunt ook de bladwijzerkoppeling uit de URL kopiëren. Beweeg de muisaanwijzer over de kopregel in Microsoft Learn om de URL te vinden. Er wordt nu een koppelingspictogram weergegeven:

Koppelingspictogram in artikelkop

Klik op het koppelingspictogram en kopieer vervolgens de ankertekst van de bladwijzer uit de URL (dat wil zeggen, het deel na de hash).

Notitie

De Learn Markdown-extensie bevat ook hulpprogramma's voor het maken van koppelingen.

De toevoeging van expliciete ankerkoppelingen via de HTML-tag <a> is niet vereist of aanbevolen, behalve in hub- en landingspagina's. Gebruik in plaats daarvan de automatisch gegenereerde bladwijzers zoals beschreven in bladwijzerkoppelingen. Geef als volgt ankers op voor hub- en landingspagina's:

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

or

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

En geef het volgende op om een koppeling naar het anker te maken:

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

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

Notitie

Ankertekst moet altijd uit kleine letters bestaan en mag geen spaties bevatten.

XRef-koppelingen zijn de aanbevolen manier om een koppeling naar API's te maken, omdat ze de koppelingstekst eenvoudig kunnen aanpassen. Daarnaast worden ze tijdens het bouwen gevalideerd en als de URL naar de API-verwijzing zou worden gewijzigd, zou de koppeling nog steeds werken. Als u in de huidige docset of andere docsets een koppeling wilt maken naar automatisch gegenereerde pagina's met API-naslaginformatie, gebruikt u XRef-koppelingen met de unieke id (UID) van het type of lid.

Tip

Met de Helper-extensie voor API Reference Link voor VS Code kunt u eenvoudig .NET API Xref-koppelingen invoegen in Markdown- en XML-bestanden.

Controleer of de API waarnaar u een koppeling wilt maken, is gepubliceerd op Microsoft Learn door alle of een deel van de volledige naam ervan te typen in de .NET API-browser of het zoekvak van Windows UWP . Als er geen resultaten worden weergegeven, is het type nog niet beschikbaar in Microsoft Learn.

Voor de syntaxis hebt u de volgende mogelijkheden:

  • Automatische koppelingen:

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

    Standaard toont de koppelingstekst alleen de naam van het lid of het type. De optionele queryparameter displayProperty=nameWithType genereert een volledig gekwalificeerde koppelingstekst, dat wil zeggen, naamruimte.type voor typen en type.lid voor typeleden, inclusief opsommingstypeleden.

  • Koppelingen in de Markdown-stijl:

    [link text](xref:UID)

    Gebruik koppelingen in de Markdown-stijl voor XRef als u de tekst van de koppeling wilt aanpassen die wordt weergegeven.

Voorbeelden:

  • <xref:System.String> wordt weergegeven als String

  • <xref:System.String?displayProperty=nameWithType> wordt weergegeven als System.String

  • [Tekenreeksklasse] (xref:System.String) wordt weergegeven als tekenreeksklasse.

De queryparameter displayProperty=fullName werkt op dezelfde manier als displayProperty=nameWithType voor klassen. Dat wil zeggen dat de koppelingstekst naamruimte.klassenaam wordt. Voor leden wordt de koppelingstekst echter weergegeven als naamruimte.classname.membername, wat mogelijk ongewenst is.

Notitie

UID's zijn hoofdlettergevoelig. Lost bijvoorbeeld <xref:System.Object> correct op, maar <xref:system.object> niet.

De UID bepalen

De UID is doorgaans gelijk aan de volledig gekwalificeerde klasse- of lidnaam. Als u de UID wilt bepalen, klikt u met de rechtermuisknop op de Microsoft Learn-pagina voor een type of lid, selecteert u Bron weergeven en kopieert u de inhoudswaarde voor ms.assetid.

ms.assetid in de bron voor webpagina

Percentagecodering van URL's

Speciale tekens in de UID moeten als volgt worden gecodeerd :

Teken HTML-codering
* *

Voorbeeld van codering:

  • System.Exception.#ctor wordt gecodeerd als System.Exception.%23ctor

Algemene typen

Algemene typen zijn typen als System.Collections.Generic.List<T>. Als u naar dit type bladert in de .NET API-browser en de bijbehorende URL bekijkt, ziet u dat <T> als -1 is geschreven in de URL, die in werkelijkheid staat voor '1:

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

Methoden

Als u een koppeling wilt maken naar een methode, kunt u een koppeling maken naar de algemene methodenpagina door een sterretje (*) toe te voegen aan de naam van de methode of aan een specifieke overbelasting. Gebruik bijvoorbeeld de algemene pagina wanneer u een koppeling wilt maken naar de methode <xref:System.Object.Equals*?displayProperty=nameWithType> zonder specifieke parametertypen. Voorbeeld:

<xref:System.Object.Equals*?displayProperty=nameWithType> maakt een koppeling naar Object.Equals

Als u een koppeling wilt maken naar een specifieke overbelasting, voegt u haakjes achter de naam van de methode toe en voegt u de volledige typenaam van elke parameter toe. Plaats geen spatie tussen de typenamen, anders werkt de koppeling niet. Voorbeeld:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> maakt een koppeling naar Object.Equals(Object, Object)

Omdat Include-bestanden deel uitmaken van een andere map moet u een langer relatief pad gebruiken. Gebruik de volgende notatie om vanuit een Include-bestand een koppeling naar een artikel te maken:

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

Tip

Met de Learn Authoring Pack-extensie voor Visual Studio Code kunt u relatieve koppelingen en bladwijzers op de juiste manier invoegen zonder dat u paden hoeft uit te zoeken.

Een selector is een navigatieonderdeel dat als vervolgkeuzelijst in een docs-artikel wordt weergegeven. Als de lezer een waarde in de vervolgkeuzelijst selecteert, wordt het geselecteerde artikel geopend in de browser. De selectorlijst bevat gewoonlijk koppelingen naar nauw verwante artikelen, bijvoorbeeld over hetzelfde onderwerp in meerdere programmeertalen, of naar een reeks nauw verwante artikelen.

Als u met selectors werkt die zijn opgenomen in een Include-bestand, gebruikt u de volgende koppelingsstructuur:

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

U kunt koppelingen met verwijzingen gebruiken zodat uw broninhoud gemakkelijker te lezen is. Bij koppelingen met verwijzingen wordt de syntaxis voor de inlinekoppeling vervangen door een eenvoudige syntaxis en kunnen de lange URL's naar het einde van het artikel worden verplaatst. Hier volgt het voorbeeld van Daring Fireball:

Inlinetekst:

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

Koppelingsverwijzingen aan het einde van het artikel:

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

Zorg ervoor dat u een spatie typt tussen de dubbele punt en de koppeling. Als u de spatie vergeet bij het maken van een koppeling naar andere technische artikelen, werkt de koppeling niet meer in het gepubliceerde artikel.

Als u een koppeling wilt maken naar een pagina in een ander Microsoft-domein (zoals de pagina met prijzen, de SLA-pagina of naar iets dat geen documentatieartikel is), gebruikt u een absolute URL, maar laat u de landcode achterwege. Het doel hier is dat de koppelingen werken in GitHub en op de weergegeven site:

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

Het beste kunt u gebruikers zo weinig mogelijk doorsturen naar andere sites. Houd in die gevallen rekening met de volgende informatie wanneer u een koppeling maakt naar sites van derden:

  • Aansprakelijkheid: maak een koppeling naar de inhoud van derden als u informatie van deze derde partij wilt delen. Het is bijvoorbeeld niet de taak van Microsoft om mensen te vertellen hoe ze Android-ontwikkeltools moeten gebruiken. Dat is namelijk de taak van Google. We kunnen eventueel wel uitleggen hoe Android-ontwikkeltools moeten worden gebruikt met Azure, maar het is aan Google om te vertellen hoe hun eigen tools moeten worden gebruikt.
  • Aftekening door PM: geef aan dat Microsoft verplicht moet aftekenen op inhoud van derden. Door een koppeling te maken, zeggen we iets over ons vertrouwen in die inhoud en onze verplichtingen als mensen de instructies volgen
  • Nieuwheidsbeoordelingen: zorg ervoor dat de informatie van derden nog steeds actueel, correct en relevant is en dat de koppeling niet is gewijzigd.
  • Offsite: zorg ervoor dat gebruikers er zich van bewust zijn dat ze naar een andere site gaan. Als dat niet blijkt uit de context, maakt u dat met een aparte zin duidelijk. Bijvoorbeeld: Bijvoorbeeld: 'Vereisten zijn de Android Developer Tools, die u kunt downloaden op de Android Studio-site'.
  • Volgende stappen: Het is prima om een koppeling toe te voegen aan bijvoorbeeld een MVP-blog in de sectie Volgende stappen. Maar nogmaals, wijs de gebruikers erop dat ze de site verlaten.
  • Juridisch: Wij worden wettelijk behandeld onder Koppelingen naar sites van derden in de voettekst Gebruiksvoorwaarden op elke microsoft.com pagina.