Metadaten und Markdownvorlage für .NET-Dokumentationen

Artikel
08/10/2023

Diese dotnet/docs-Vorlage enthält Beispiele für die Markdownsyntax sowie Anweisungen zum Einstellen der Metadaten.

Beim Erstellen einer Markdowndatei sollten Sie die enthaltene Vorlage in eine neue Datei kopieren, die Metadaten wie unten gezeigt ausfüllen und den Titel des Artikels in der obigen H1-Überschrift festlegen.

Metadaten

Der erforderliche Metadatenblock befindet sich im folgenden Metadatenblockbeispiel:

---
title: [ARTICLE TITLE]
description: [usually a summary of your first paragraph. It gets displayed in search results, and can help drive the correct traffic if well written.]
author: [GITHUB USERNAME]
ms.date: [CREATION/UPDATE DATE - mm/dd/yyyy]
---
# The H1 should not be the same as the title, but should describe the article contents

Sie müssen zwischen dem Doppelpunkt („:“) und dem Wert eines Metadatenelements ein Leerzeichen setzen.
Doppelpunkte in einem Wert (z.B. in einem Titel) unterbrechen den Metadatenparser. In diesem Fall müssen Sie doppelte Anführungszeichen um den Titel setzen (z.B. title: "Writing .NET Core console apps: An advanced step-by-step guide").
title: Wird in den Ergebnissen von Suchmaschinen angezeigt. Der Titel sollte nicht mit dem Titel in Ihrer H1-Überschrift übereinstimmen und darf maximal 60 Zeichen enthalten.
description: Zusammenfassung des Artikelinhalts. Für gewöhnlich wird diese Beschreibung in den Suchergebnissen angezeigt, jedoch wird sie nicht für die Suchrangfolge verwendet. Einschließlich der Leerzeichen sollte die Länge der Beschreibung zwischen 115 und 145 Zeichen liegen.
author: Das Feld „author“ (Autor) sollte den GitHub-Benutzernamen des Autors enthalten.
ms.date: Das Datum des letzten wichtigen Updates. Aktualisieren Sie dieses Datum bei vorhandenen Artikeln, wenn Sie einen gesamten Artikel prüfen und aktualisieren. Kleine Fehlerbehebungen, z.B. Tippfehler oder ähnliches, rechtfertigen ein Update nicht.

An jeden Artikel werden weitere Metadaten angefügt, allerdings werden die meisten Metadatenwerte in der Regel auf der Ordnerebene angewendet. Dies wird in der Datei docfx.json angegeben.

Grundlegendes Markdown, GFM und Sonderzeichen

Die Grundlagen von Markdown, GFM (GitHub Flavored Markdown) und OPS-spezifischen Erweiterungen können Sie anhand des Artikels Markdownreferenz erlernen.

Markdown verwendet Sonderzeichen wie *, ` und # für die Formatierung. Wenn Sie eines dieser Zeichen in Ihren Inhalt einfügen möchten, müssen Sie eine der folgenden Vorgehensweisen anwenden:

Versehen Sie das Sonderzeichen mit einem umgekehrten Schrägstrich als Escapezeichen (z. B. \* für ein *).
Verwenden Sie den HTML-Entitätscode für das Zeichen (z. B. * für ein *).

Dateinamen

Dateinamen unterliegen folgenden Regeln:

Nur Kleinbuchstaben, Zahlen und Bindestriche sind zulässig.
Leer- oder Satzzeichen sind nicht erlaubt. Worte und Zahlen im Dateinamen werden durch Bindestriche getrennt.
Verwenden Sie Verben, die den Zweck angeben, z.B. develop, buy, build, troubleshoot. Auf „-ing“ endenden Worte dürfen nicht verwendet werden.
Kurze Worte wie a, and, the, in, or usw. sind nicht erlaubt.
Das Markdownformat und die Erweiterung „.md“ sind erforderlich.
Verwenden Sie angemessene, kurze Dateinamen. Sie sind Teil der URL für Ihre Artikel.

Überschriften

Verwenden Sie für Überschriften die Standardgroß- und kleinschreibung. Schreiben Sie das erste Wort einer Überschrift immer groß.

Textformatierung

Kursiv
Für Dateien, Ordner, Pfade (für lange Elemente, die in Ihre eigene Zeile getrennt werden) und neue Begriffe

Fett
Für Benutzeroberflächenelemente

Code
Für Inlinecode, Schlüsselwörter der Sprache, NuGet-Paketnamen, Befehlszeilenbefehle, Datenbanktabellen- und Spaltennamen sowie URLs, die nicht klickbar sein sollen

Links

Informationen zu Ankern, internen Links, Links zu anderen Dokumenten, Codeeinfügungen und externen Links finden Sie im allgemeinen Artikel zu Links.

Das Team für die .NET-Dokumentation wendet folgende Konventionen an:

In den meisten Fällen werden relative Links verwendet. Von der Verwendung von ~/ wird in Links abgeraten, weil relative Links zur Quelle auf GitHub führen. Allerdings wird das Zeichen ~/ für Links zu Dateien in abhängigen Repositorys verwendet, um den Pfad anzugeben. Da die Dateien im abhängigen Repository sich auf GitHub an einem anderen Speicherort befinden, werden die Links mit relativen Links, unabhängig davon, wie sie geschrieben sind, nicht richtig aufgelöst.
Die C#-Sprachspezifikation und die Visual Basic-Sprachspezifikation sind in den .NET-Dokumentationen enthalten, indem die Quelle der Sprach-Repositorys eingebunden wird. Die Markdownquellen werden in den Repositorys csharplang und vblang verwaltet.

Links zu den Sprachspezifikationen müssen zu den Quellverzeichnissen zeigen, in denen diese Spezifikationen enthalten sind. Für C# ist das Verzeichnis ~/_csharplang/spec, und für Visual Basic ist das Verzeichnis ~/_vblang/spec. Dies wird im folgenden Beispiel veranschaulicht:

[C# Query Expressions](~/_csharplang/spec/expressions.md#query-expressions)

Links zu APIs

Das Buildsystem verfügt über einige Erweiterungen, mit denen Sie Links zu .NET-APIs erstellen können, ohne externe Links verwenden zu müssen. Verwenden Sie eine der folgenden Syntaxvarianten:

Automatische Verknüpfung: <xref:UID> oder <xref:UID?displayProperty=nameWithType>

Der displayProperty-Abfrageparameter erzeugt einen vollqualifizierten Linktext. Standardmäßig zeigt der Linktext nur den Member- oder Typnamen an.
Markdownlink: [link text](xref:UID)

Verwenden Sie den Markdownlink, wenn Sie den angezeigten Linktext anpassen möchten.

Beispiele:

<xref:System.String> wird als Zeichenfolge gerendert
<xref:System.String?displayProperty=nameWithType> wird als System.String gerendert
[String class](xref:System.String) wird als Zeichenfolgenklasse gerendert

Weitere Informationen zur Verwendung dieser Notation finden Sie unter Using cross reference (Verwenden des Querverweises).

Wenn die UID die Sonderzeichen `, # oder * enthält, muss der UID-Wert jeweils als %60, %23 und %2A im HTML-Format codiert werden. Manchmal sehen Sie die Codierung mit Klammern, aber dies ist nicht erforderlich.

Beispiele:

System.Threading.Tasks.Task`1 wird zu System.Threading.Tasks.Task%601
System.Exception.#ctor wird zu System.Exception.%23ctor
System.Lazy`1.#ctor(System.Threading.LazyThreadSafetyMode) wird zu System.Lazy%601.%23ctor%28System.Threading.LazyThreadSafetyMode%29

Die UIDs von Typen, eine Liste von überladenen Membern oder einen bestimmten überladenen Member finden Sie über https://xref.learn.microsoft.com/autocomplete. Die Abfragezeichenfolge ?text=*\<type-member-name>* gibt den Typ oder Member an, dessen UIDs Sie abrufen möchten. https://xref.learn.microsoft.com/autocomplete?text=string.format ruft beispielsweise die Überladungen String.Format ab. Das Tool sucht in der UID nach dem angegebenen Abfrageparameter text. Zum Beispiel können Sie nach Membernamen (ToString), partiellen Membernamen (ToStri), Typen und Membernamen (Double.ToString) und mehr suchen.

Wenn Sie ein * ( oder %2A) hinter der UID hinzufügen, steht der Link für die Überladungsseite und nicht für eine bestimmte API. Dies können Sie z. B. verwenden, wenn Sie eine Verknüpfung mit der Seite List<T>.BinarySearch-Methode auf generische Weise als Alternative zu einer bestimmten Überladung wie List<T>.BinarySearch (T, IComparer<T>) herstellen möchten. Sie können auch * verwenden, um einen Link zu einer Memberseite zu erstellen, wenn der Member nicht überladen ist. Damit ersparen Sie sich das Einfügen der Parameterliste in die UID.

Sie müssen den vollqualifizierten Namen des Typs jedes Parameters der Methode einfügen, um einen Link zu einer spezifischen Methodenüberladung zu erstellen. Zum Beispiel führt <xref:System.DateTime.ToString> zu der parameterlosen Methode DateTime.ToString, und <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> führt zu der Methode DateTime.ToString(String,IFormatProvider).

Verwenden Sie zum Verknüpfen eines generischen Typs (z. B. System.Collections.Generic.List<T>) das Zeichen ` (%60) gefolgt von der Anzahl generischer Typparameter. Zum Beispiel führt <xref:System.Nullable%601> zum Typ System.Nullable<T>, und <xref:System.Func%602> führt zum Delegaten System.Func<T,TResult>.

Code

Die beste Methode zum Einfügen von Code besteht darin, Ausschnitte aus einem funktionstüchtigen Beispiel einzufügen. Erstellen Sie Ihr Beispiel anhand der Anweisungen im Artikel Contributing to .NET (Mitwirken an .NET). Durch Einfügen von Ausschnitten aus vollständigen Programmen wird sichergestellt, dass der gesamte Code das CI-System (Continuous Integration) durchläuft. Wenn Sie jedoch etwas veranschaulichen müssen, das zu Fehlern zur Kompilier- oder Laufzeit führt, können Sie Inlinecodeblöcke verwenden.

Informationen zur Markdownsyntax zum Anzeigen von Code in Dokumenten finden Sie unter Gewusst wie: Einbinden von Code in Dokumenten.

Bilder

Statisches Bild oder animiertes GIF

![this is the alt text](../images/Logo_DotNet.png)

Verknüpftes Bild

[![alt text for linked image](../images/Logo_DotNet.png)](https://dot.net)

Videos

Sie können YouTube-Videos in eine Markdowndatei einbetten. Klicken Sie mit der rechten Maustaste auf das Video, und wählen Sie Einbettungscode kopieren aus <iframe>, um die richtige URL des Videos abzurufen.

> [!VIDEO <youtube_video_link>]

Beispiel:

> [!VIDEO https://www.youtube.com/embed/Q2mMbjw6cLA]

learn.microsoft-Erweiterungen

learn.microsoft bietet einige zusätzliche Erweiterungen für GitHub Flavored Markdown.

Listen mit Häkchen

Für Listen ist eine benutzerdefinierte Formatvorlage verfügbar. Sie können Listen mit grünen Häkchen ausgeben.

> [!div class="checklist"]
> * How to create a .NET Core app
> * How to add a reference to the Microsoft.XmlSerializer.Generator package
> * How to edit your MyApp.csproj to add dependencies
> * How to add a class and an XmlSerializer
> * How to build and run the application

Dies wird wie folgt dargestellt:

Erstellen einer .NET Core-App
Hinzufügen eines Verweises zum Microsoft.XmlSerializer.Generator-Paket
Bearbeiten Ihrer MyApp.csproj-Datei zum Hinzufügen von Abhängigkeiten
Hinzufügen von „XmlSerializer“ und einer Klasse
Erstellen und Ausführen der Anwendung

Ein Beispiel der Liste mit Häkchen finden Sie in dieser .NET Core-Dokumentation.

Schaltflächen

Schaltflächenlinks:

> [!div class="button"]
> [button links](dotnet-contribute.md)