Freigeben über

Metadaten- und Markdown-Vorlage für .NET-Dokumente

Diese Dotnet/Docs-Vorlage enthält Beispiele für markdown-Syntax und Anleitungen zum Festlegen der Metadaten.

Kopieren Sie beim Erstellen einer Markdown-Datei die enthaltene Vorlage in eine neue Datei, füllen Sie die Metadaten wie unten angegeben aus, und legen Sie die Überschrift H1 oben auf den Titel des Artikels fest.

Metadaten

Der erforderliche Metadatenblock befindet sich im folgenden Beispielmetadatenblock:

---
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 ein Leerzeichen zwischen dem Doppelpunkt (:) und dem Wert für ein Metadatenelement haben.
  • Doppelpunkte in einem Wert (z. B. ein Titel) unterbrechen den Metadatenparser. Geben Sie in diesem Fall den Titel in doppelte Anführungszeichen ein (z. B title: "Writing .NET Core console apps: An advanced step-by-step guide". ).
  • title: Wird in Suchergebnissen der Suchmaschine angezeigt. Der Titel sollte nicht mit dem Titel in der Überschrift H1 identisch sein, und er sollte mindestens 60 Zeichen enthalten.
  • beschreibung: Fasst den Inhalt des Artikels zusammen. Sie wird in der Regel auf der Suchergebnisseite angezeigt, wird jedoch nicht für die Suchbewertung verwendet. Die Länge sollte 115 bis 145 Zeichen umfassen, einschließlich Leerzeichen.
  • author: Das Autorenfeld sollte den GitHub-Benutzernamen des Autors enthalten.
  • ms.date: Das Datum der letzten signifikanten Aktualisierung. Aktualisieren Sie dies in vorhandenen Artikeln, wenn Sie den gesamten Artikel überprüft und aktualisiert haben. Kleine Fixes, z. B. Tippfehler oder ähnliche, garantieren kein Update.

Andere Metadaten sind jedem Artikel zugeordnet, aber in der Regel wenden wir die meisten Metadatenwerte auf Ordnerebene an, die in docfx.jsonangegeben sind.

Grundlegende Markdown-, GFM- und Sonderzeichen

Sie können die Grundlagen von Markdown, GitHub Flavored Markdown (GFM) und OPS-spezifischen Erweiterungen im Markdown-Referenzartikel erlernen.

Markdown verwendet Sonderzeichen wie "*", "" und "#" für die Formatierung. Wenn Sie eines dieser Zeichen in Ihren Inhalt aufnehmen möchten, müssen Sie eine von zwei Dingen ausführen:

  • Setzen Sie einen Backslash vor das Sonderzeichen, um es zu „escapen“ (z. B. \* für ein *).
  • Verwenden Sie den HTML-Entitätscode für das Zeichen (z. B. * für ein *).

Dateinamen

Dateinamen verwenden die folgenden Regeln:

  • Enthält nur Kleinbuchstaben, Zahlen und Bindestriche.
  • Keine Leerzeichen oder Interpunktionszeichen. Verwenden Sie die Bindestriche, um Wörter und Zahlen im Dateinamen zu trennen.
  • Verwenden Sie Aktionsverben, die spezifisch sind, z. B. Entwickeln, Kaufen, Erstellen, Problembehandlung. Keine Wörter mit der Endung -ing.
  • Keine kleinen Wörter - schließen Sie kein a, und, das, in, oder usw. ein.
  • Muss in Markdown sein und die Dateierweiterung .md verwenden.
  • Halten Sie Dateinamen relativ kurz. Sie sind Teil der URL für Ihre Artikel.

Überschriften

Verwenden Sie Satzanfangsgroßschreibung. Immer das erste Wort einer Überschrift großschreiben.

Textformatierung

Italics
Wird für Dateien, Ordner, Pfade und neue Begriffe verwendet; bei langen Elementen werden sie auf ihre eigene Zeile gesetzt.

Bold
Wird für UI-Elemente verwendet.

Code
Wird für Inlinecode, Sprachstichwörter, NuGet-Paketnamen, Befehlszeilenbefehle, Datenbanktabellen- und Spaltennamen und URLs verwendet, auf die Sie nicht klicken möchten.

Im allgemeinen Artikel über Links finden Sie Informationen zu Ankern, internen Links, Links zu anderen Dokumenten, Codeeinbindungen und externen Links.

Das .NET-Dokumentteam verwendet die folgenden Konventionen:

  • In den meisten Fällen verwenden wir relative Links und raten davon ab, ~/ in Links zu verwenden, da relative Links in der Quelle auf GitHub aufgelöst werden. Wenn wir jedoch eine Verknüpfung mit einer Datei in einem abhängigen Repository herstellen, verwenden wir das ~/ Zeichen, um den Pfad anzugeben. Da sich die Dateien im abhängigen Repository an einem anderen Speicherort in GitHub befinden, werden die Links unabhängig davon, wie sie geschrieben wurden, nicht ordnungsgemäß mit relativen Links aufgelöst.
  • Die C#-Sprachspezifikation und die Visual Basic-Sprachspezifikation sind in den .NET-Dokumenten enthalten, indem sie die Quelle aus den Sprachrepositorys einschließen. Die Markdownquellen werden in den Csharplang - und vblang-Repositorys verwaltet.

Links zu der Spezifikation müssen auf die Quellverzeichnisse verweisen, in denen diese Spezifikationen enthalten sind. Für C# ist es ~/_csharplang/spec und für VB, es ist ~/_vblang/spec, wie im folgenden Beispiel gezeigt:

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

Das Buildsystem verfügt über einige Erweiterungen, mit denen wir eine Verknüpfung mit .NET-APIs herstellen können, ohne externe Links verwenden zu müssen. Sie verwenden eine der folgenden Syntaxen:

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

    Der displayProperty Abfrageparameter erzeugt einen vollqualifizierten Linktext. Der Linktext zeigt standardmäßig nur den Element- oder Typnamen an.

  2. Markdown-Link: [link text](xref:UID)

    Verwenden Sie diese Einstellung, 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) rendert als String-Klasse

Weitere Informationen zur Verwendung dieser Schreibweise finden Sie unter Verwenden von Querverweis.

Einige UIDs enthalten die Sonderzeichen ", # oder *, der UID-Wert muss html-codiert sein als %60, %23 bzw %2A . Manchmal werden Klammern codiert angezeigt, aber es ist keine Anforderung.

Beispiele

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

Wenn Sie nach der UID ein * (oder %2A) hinzufügen, stellt der Link die Überladungsseite und keine bestimmte API dar. Sie können dies beispielsweise verwenden, wenn Sie in generischer Weise einen Link zur Seite der List<T>.BinarySearch-Methode herstellen möchten, anstatt einer spezifischen Überladung wie List<T>.BinarySearch(T, IComparer<T>). Sie können auch * verwenden, um einen Link zu einer Mitgliedsseite zu erstellen, wenn das Mitglied nicht überladen ist; so sparen Sie sich das Einfügen der Parameterliste in die UID.

Um eine Verknüpfung mit einer bestimmten Methodenüberladung zu erstellen, müssen Sie den vollqualifizierten Typnamen der einzelnen Parameter der Methode angeben. Beispielsweise <verknüpft xref:System.DateTime.ToString> mit der parameterlosen DateTime.ToString-Methode , während <xref:System.DateTime.ToString(System.String,System.IFormatProvider)> mit der DateTime.ToString(String,IFormatProvider) -Methode verknüpft ist.

Zum Verknüpfen mit einem generischen Typ, wie System.Collections.Generic.List<T>, verwenden Sie das Zeichen `%60 gefolgt von der Anzahl der generischen Typparameter. Beispielsweise verweist <xref:System.Nullable%601> auf den System.Nullable<T>-Typ, während <xref:System.Func%602> auf den System.Func<T,TResult>-Delegat verweist.

Code

Die beste Möglichkeit zum Einschließen von Code besteht darin, Codeausschnitte aus einem arbeitsfähigen Beispiel einzuschließen. Erstellen Sie Ihr Beispiel anhand der Anweisungen im Artikel 'Mitwirken zu .NET'. Das Einschließen von Codeausschnitten aus vollständigen Programmen stellt sicher, dass der gesamte Code über unser Ci-System (Continuous Integration) ausgeführt wird. Wenn Sie jedoch etwas anzeigen müssen, das Kompilierungszeit- oder Laufzeitfehler verursacht, können Sie Inlinecodeblöcke verwenden.

Informationen zur Markdown-Syntax zum Anzeigen von Code in Dokumenten finden Sie unter Einfügen von Code in Dokumente.

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)

Videoaufnahmen

Sie können YouTube-Videos in eine Markdown-Datei einbetten. Um die richtige URL des Videos abzurufen, klicken Sie mit der rechten Maustaste auf das Video, wählen Sie "Einbindungscode kopieren" aus, und kopieren Sie die URL aus dem <iframe> Element.

> [!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.

Überprüfte Listen

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

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

So wird es gerendert:

  • So erstellen Sie eine .NET Core-App
  • So fügen Sie einen Verweis auf das Microsoft.XmlSerializer.Generator-Paket hinzu
  • So bearbeiten Sie Ihre MyApp.csproj, um Abhängigkeiten hinzuzufügen
  • Hinzufügen einer Klasse und eines XmlSerializers
  • Erstellen und Ausführen der Anwendung

Sie können ein Beispiel für kontrollierte Listen in Aktion in den .NET Core-Dokumenten sehen.

Knöpfe

Schaltflächenlinks:

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

So wird es gerendert:

Schaltflächenlinks

In den Visual Studio-Dokumenten wird ein Beispiel für Schaltflächen in Aktion angezeigt.

Schritt-für-Schritt-Anleitungen

>[!div class="step-by-step"]
> [Pre](../docs/csharp/expression-trees-interpreting.md)
> [Next](../docs/csharp/expression-trees-translating.md)

Sie können ein Beispiel für schrittweise Schritte in Aktion im C#-Leitfaden sehen.

  • Last updated on