Verwenden von Links in der Dokumentation

In diesem Artikel erfahren Sie, wie Sie Links von Seiten verwenden, die auf Microsoft Learn gehostet werden. Links können mit wenigen unterschiedlichen Konventionen auf einfache Weise in Markdown eingefügt werden. Benutzer werden über Links auf Inhalte derselben Seite, auf benachbarten Seiten oder auf externen Websites und URLs verwiesen.

Das Back-End von Microsoft Learn nutzt Open Publishing Services (OPS). Dadurch wird CommonMark-konformes Markdown unterstützt, das durch die Markdig-Engine analysiert wird. Diese Markdown-Variante ist meistens mit GitHub Flavored Markdown (GFM) kompatibel, da die meisten Dokumentationen auf GitHub gespeichert und auch dort bearbeitet werden können. Weitere Funktionalität wird über Markdown-Erweiterungen hinzugefügt.

Wichtig

Alle Links müssen sicher sein (https und http), sofern das Ziel dies unterstützt.

Linktext

Die im Linktext verwendeten Begriffe sollten benutzerfreundlich sein. Das bedeutet, es sollten geläufige Begriffe oder der Titel einer Seite sein, auf die Sie verweisen.

Wichtig

Verwenden Sie „Hier klicken“ nicht als Linktext. Diese ist im Hinblick auf die Suchmaschinenoptimierung suboptimal und beschreibt das Linkziel nicht ausreichend.

Richtig:

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

Falsch:

• 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 in einem Artikel zum anderen Artikel

Das Veröffentlichungssystem unterstützt zwei Arten von Links: URLs und Dateiverknüpfungen.

Bei einem URL-Link kann es sich um einen zum Stammverzeichnis von https://learn.microsoft.com relativen URL-Pfad handeln, oder um eine absolute URL, die die vollständige URL-Syntax enthält (z. B. https://github.com/MicrosoftDocs/PowerShell-Docs).

• Verwenden Sie URL-Links, wenn Sie Inhalt außerhalb des aktuellen Docsets oder zwischen automatisch generierten Referenz- und Konzeptartikeln innerhalb des Docsets verlinken.
• Die einfachste Möglichkeit zum Erstellen eines relativen Links besteht darin, die URL aus Ihrem Browser zu kopieren und dann https://learn.microsoft.com/en-us aus dem Wert zu entfernen, den Sie in den Markdowncode einfügen.
• URLs für Microsoft-Eigenschaften sollten keine Gebietsschemas enthalten. Entfernen Sie also beispielsweise /en-us aus der URL.

Ein Dateilink wird verwendet, um einen Artikel mit einem anderen innerhalb des Docsets zu verlinken.

• Für alle Dateipfade müssen Schrägstriche (/) anstelle von umgekehrten Schrägstrichen verwendet werden.

• Einem Artikel wird ein Link zu einem anderen Artikel im selben Verzeichnis hinzugefügt:

  [link text](article-name.md)

• Ein Artikel verweist auf einen Artikel im übergeordneten Verzeichnis des aktuellen Verzeichnisses:

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

• Ein Artikel verweist auf einen Artikel in einem Unterverzeichnis des aktuellen Verzeichnisses:

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

• Ein Artikel verweist auf einen Artikel in einem Unterverzeichnis des übergeordneten Verzeichnisses des aktuellen Verzeichnisses:

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

• Einige Artikel bestehen aus einer .yml- und einer .md-Datei, wobei die .yml-Datei Metadaten und die .md-Datei den Inhalt enthält. Erstellen Sie in diesem Fall eine Verknüpfung zur .yml-Datei.

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

Hinweis

In keinem der oben stehenden Beispiele wird ~/ als Teil des Links verwendet. Wenn Sie auf einen absoluten Pfad verweisen möchten, der im Stammverzeichnis des Repositorys beginnt, beginnen Sie den Link mit /. Wenn Sie ein ~/ einfügen, wird dadurch beim Navigieren in den Quellrepositorys auf GitHub ein ungültiger Link erstellt. Wenn der Pfad mit / beginnt, kann der Link ordnungsgemäß aufgelöst werden.

Struktur der Links auf Microsoft Learn

Auf Microsoft Learn veröffentlichte Inhalte weisen die folgende URL-Struktur auf:

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

Beispiele:

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

https://learn.microsoft.com/powershell/azure/overview?view=azurermps-5.1.1

• <locale>: gibt die Sprache des Artikels an (Beispiel: de-de oder en-us)
• <product-service>: gibt den Namen des Produkts oder Diensts an (Beispiel: powershell, dotnet oder azure)
• [<feature-service>] (optional): gibt den Featurenamen oder Subdienst des Produkts an (Beispiel: csharp oder load-balancer)
• [<subfolder>] (optional): der Name eines Unterordners innerhalb eines Features
• <topic>: der Name der Artikeldatei für das Thema (Beispiel: load-balancer-overview oder overview)
• [?view=\<view-name>] (optional): der Ansichtsname, der von der Versionsauswahl für Inhalt mit mehreren verfügbaren Versionen verwendet wird (Beispiel: azps-3.5.0)

Tipp

Artikel im selben Docset besitzen meistens das gleiche <product-service>-URL-Fragment. Zum Beispiel:

• Gleiches Docset:
  • https://learn.microsoft.com/dotnet/core/get-started
  • https://learn.microsoft.com/dotnet/framework/install
• Anderes Docset:
  • https://learn.microsoft.com/dotnet/core/get-started
  • https://learn.microsoft.com/visualstudio/whats-new

Lesezeichenlinks

Verwenden Sie ein Hashsymbol gefolgt von der Überschrift in Kleinbuchstaben, um einen Lesezeichenlink zu einer Überschrift in der aktuellen Datei zu erstellen. Entfernen Sie Satzzeichen aus der Überschrift, und ersetzen Sie Leerzeichen durch Bindestriche:

[Managed Disks](#managed-disks)

Wenn Sie eine Lesezeichenüberschrift in einem anderen Artikel verlinken möchten, verwenden Sie einen datei- oder websitebezogenen Link und ein Hashsymbol gefolgt von der Überschrift. Entfernen Sie Satzzeichen aus der Überschrift, und ersetzen Sie Leerzeichen durch Bindestriche:

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

Sie können auch den Lesezeichenlink aus der URL kopieren. Zeigen Sie mit der Maus auf die Kopfzeile von Microsoft Learn, um zur URL zu gelangen. Das Linksymbol sollte angezeigt werden:

Klicken Sie auf das Linksymbol, und kopieren Sie dann den Ankertext des Lesezeichens aus der URL (d. h. den Teil nach dem Hash).

Hinweis

Die Learn Markdown-Erweiterung bietet auch Tools zum Erstellen von Links.

Explizite Ankerlinks

Es ist nicht erforderlich und wird nicht empfohlen, explizite Ankerlinks mit dem HTML-Tag <a> hinzufügen (Ausnahmen: im Hub und auf der Landing Page). Verwenden Sie stattdessen wie unter Lesezeichenlinks beschrieben die automatisch generierten Lesezeichen. Deklarieren Sie folgendermaßen Anker für den Hub und die Landing Page:

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

or

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

So können Sie einen Link zum Anker erstellen:

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

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

Hinweis

Ankertext muss immer aus Kleinbuchstaben bestehen und darf keine Leerzeichen enthalten.

XRef-Links (Querverweise)

XRef-Links sind die empfohlene Methode zum Erstellen von Verknüpfungen mit APIs, da sie das Anpassen des Linktexts vereinfachen. Darüber hinaus werden sie zum Zeitpunkt der Erstellung überprüft, und der Link funktioniert auch dann, wenn sich die URL der API-Referenz ändern sollte. Verwenden Sie XRef-Links mit der eindeutigen ID (UID) des Typs oder Members, um automatisch generierte Links zu API-Referenzen im aktuellen Docset oder in anderen Docsets hinzuzufügen.

Tipp

Die Erweiterung API Reference Link Helper für VS Code erleichtert das Einfügen von .NET-API-Xref-Links in Markdown- und XML-Dateien.

Überprüfen Sie, ob die API, die Sie verlinken möchten, sich auf Microsoft Learn befindet, indem Sie ihren Namen ganz oder teilweise in den .NET-API-Browser oder das Windows UWP-Suchfeld eingeben. Wenn keine Ergebnisse angezeigt werden, ist sie noch nicht auf Microsoft Learn vorhanden.

Sie können eine der folgenden Syntaxvarianten auswählen:

• Automatische Links:

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

  Im Linktext wird standardmäßig nur der Member- oder Typname angezeigt. Der optionale Abfrageparameter displayProperty=nameWithType erzeugt einen vollqualifizierten Linktext, der namespace.typ für Typen und typ.member für Typmember (inklusive Enumerationstypenmember) lautet.

• Markdownlinks:

  [link text](xref:UID)
  

  Verwenden Sie Markdownlinks für XRef, wenn Sie den angezeigten Linktext anpassen möchten.

Beispiele:

• <xref:System.String> wird als String angezeigt.

• <xref:System.String?displayProperty=nameWithType> wird als System.String angezeigt.

• [String class](xref:System.String) wird als String-Klasse angezeigt.

Der Abfrageparameter displayProperty=fullName funktioniert genau wie displayProperty=nameWithType für Klassen. Der Linktext wird also zu namespace.klassenname. Für Member wird der Linktext jedoch als namespace.classname.membername angezeigt. Das ist möglicherweise nicht erwünscht.

Hinweis

Bei UIDs wird die Groß-/Kleinschreibung berücksichtigt. Beispielsweise wird <xref:System.Object> ordnungsgemäß aufgelöst, <xref:system.object> jedoch nicht.

Ermitteln der UID

Die UID entspricht in der Regel dem vollqualifizierten Klassen- oder Membernamen. Zum Festlegen der UID klicken Sie mit der rechten Maustaste auf die Seite Microsoft Learn eines Typs oder Members. Klicken Sie dann auf Quelltext anzeigen und kopieren Sie den content-Wert von ms.assetid.

Prozentcodierung von URLs

Sonderzeichen in der UID müssen folgendermaßen als Prozentwert codiert werden:

Zeichen	HTML-Codierung
*	*

Codierungsbeispiel:

• System.Exception.#ctor wird als System.Exception.%23ctor codiert.

Generische Typen

Bei generischen Typen handelt es sich um Typen wie System.Collections.Generic.List<T>. Wenn Sie einen solchen Typ im .NET-API-Browser suchen, stellen Sie bei der URL fest, dass <T> im Format -1 dargestellt wird und somit eigentlich für `1 steht:

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

Methoden

Für die Verlinkung mit einer Methode können Sie entweder einen Link zur allgemeinen Methodenseite erstellen, indem Sie ein Sternchen (*) an den Methodennamen anfügen, oder zu einer bestimmten Überladung. Verwenden Sie die allgemeine Seite beispielsweise, wenn Sie einen Link zur <xref:System.Object.Equals*?displayProperty=nameWithType>-Methode ohne bestimmte Parametertypen erstellen möchten. Zum Beispiel:

<xref:System.Object.Equals*?displayProperty=nameWithType> verlinkt zu Object.Equals.

Für eine Verlinkung zu einer bestimmten Überladung müssen Sie nach dem Methodennamen Klammern einfügen und dort die vollständigen Namen der einzelnen Parameter eingeben. Fügen Sie kein Leerzeichen zwischen den Typnamen ein, da der Link andernfalls nicht funktioniert. Zum Beispiel:

<xref:System.Object.Equals(System.Object,System.Object)?displayProperty=nameWithType> verlinkt zu Object.Equals(Object, Object).

Links von Includes

Da sich include-Dateien in einem anderen Verzeichnis befinden, müssen Sie längere relative Pfade verwenden. Verwenden Sie zum Erstellen eines Links zu einem Artikel aus einer include-Datei folgendes Format:

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

Tipp

Mit der Erweiterung Learn Authoring Pack für Visual Studio Code können Sie relative Links und Lesezeichenlinks korrekt einfügen, ohne sich um den Pfad Gedanken machen zu müssen.

Links in Selektoren

Ein Selektor ist eine Komponente zum Navigieren, die in einem Dokumentationsartikel als Dropdownliste angezeigt wird. Wenn ein Leser einen Wert in der Dropdownliste auswählt, wird der ausgewählte Artikel im Browser geöffnet. In der Regel enthält die Selektorliste Links zu Artikeln, die in engem Zusammenhang stehen, z.B. der gleiche Inhalt in mehreren Programmiersprachen oder eine zusammenhängende Reihe von Artikeln.

Wenn Sie in einer Includedatei eingebettete Selektoren verwenden, verwenden Sie folgende 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)

Verweislinks

Zur besseren Lesbarkeit Ihres Quellinhalts können Sie Verweislinks verwenden. Die Verweislinks ersetzen die Syntax des Inlinelinks durch eine vereinfachte Syntax, mit der Sie lange URLs an das Ende des Artikels verschieben können. Im Folgenden wird ein Beispiel aus dem Blog Daring Fireball vorgestellt:

Inlinetext:

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

Linkverweise am Ende des Artikels:

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

Achten Sie darauf, dass Sie nach dem Doppelpunkt und vor dem Link ein Leerzeichen einfügen. Wenn Sie einen Link zu anderen technischen Artikeln einfügen und das Leerzeichen vergessen, ist der Link im veröffentlichten Artikel fehlerhaft.

Link zu Seiten außerhalb der technischen Dokumentation

Zum Erstellen eines Links zu einer Seite zu einer anderen Microsoft-Eigenschaft (z.B. einer Seite mit Preisen oder der SLA oder einer anderen Seite, die kein Dokumentationsartikel ist), verwenden Sie eine absolute URL, wobei Sie jedoch das Gebietsschema auslassen. Hierdurch soll die Funktionsfähigkeit von Links in GitHub und auf der gerenderten Website sichergestellt werden:

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

Links zu Websites Dritter

Um eine ideale Benutzererfahrung sicherzustellen, sollten Benutzer so selten wie möglich an andere Websites verwiesen werden. Daher sollten beim Hinzufügen von Links zu Websites von Drittanbietern, was gelegentlich notwendig ist, folgende Punkte berücksichtigt werden:

• Verantwortlichkeit: Links zu Inhalten von Drittanbietern, wenn die Informationen, die geteilt werden sollen, von Drittanbietern stammen. Beispielsweise liegt es nicht im Zuständigkeitsbereich von Microsoft, Benutzer über die Verwendung von Android-Entwicklertools zu informieren – dies ist die Aufgabe von Google. Bei Bedarf können wir erläutern, wie Android-Entwicklertools im Zusammenhang mit Azure zu verwenden sind. Doch die allgemeine Erläuterung bezüglich der Verwendung dieser Tools obliegt Google.
• Freigabe durch einen PM: Stellen Sie die Anforderung, dass Inhalte von Drittanbietern durch Microsoft freigegeben werden. Durch die Erstellung von Links zu diesen Inhalten drücken wir unser Vertrauen in diese Inhalte aus und müssen gewisse Pflichten erfüllen, wenn Benutzer die Anweisungen befolgen.
• Prüfung der Aktualität: Stellen Sie sicher, dass Informationen von Drittanbietern nach wie vor aktuell, korrekt und relevant sind und dass sich der Link nicht geändert hat.
• Hinweis auf Umleitung an externe Websites: Benutzer müssen darauf hingewiesen werden, dass sie auf eine andere Website umgeleitet werden. Wenn sich dies nicht eindeutig aus dem Kontext ergibt, fügen Sie einen entsprechenden Hinweis hinzu. Zum Beispiel: „Zu den Voraussetzungen zählen die Android-Entwicklertools. Diese können Sie über die Android Studio-Website herunterladen.“
• Nächste Schritte: Im Abschnitt „Nächste Schritte“ können Sie beispielsweise einen Link zu einem Blog von einem MVP hinzufügen. Auch hier müssen Benutzer lediglich darauf hingewiesen werden, dass sie im Begriff sind, die Website zu verlassen.
• Rechtliche Hinweise: Durch die Nutzungsbedingungen in der Fußzeile jeder „microsoft.com“-Seite sind wir in Bezug auf Links zu Websites von Drittanbietern rechtlich geschützt.