Bewährte Methoden für Markdown

Dieser Artikel enthält spezifische Anleitungen für die Verwendung von Markdown in unserer Dokumentation. Es ist kein Lernprogramm für Markdown. Wenn Sie ein Lernprogramm für Markdown benötigen, lesen Sie dieses Markdown-Cheatsheet.

Die Buildpipeline, die unsere Dokumentation erstellt, verwendet markdig zum Verarbeiten der Markdown-Dokumente. Markdig analysiert die Dokumente basierend auf den Regeln der neuesten CommonMark-Spezifikation . OPS folgt der CommonMark-Spezifikation und fügt einige Erweiterungen für plattformspezifische Features hinzu, z. B. Tabellen und Warnungen.

Die CommonMark-Spezifikation ist bei der Konstruktion einiger Markdown-Elemente strenger. Achten Sie auf die details, die in diesem Dokument angegeben sind.

Wir verwenden die Markdownlint-Erweiterung in VS Code, um unsere Stil- und Formatierungsregeln zu erzwingen. Diese Erweiterung wird als Teil des Lernerstellungspakets installiert.

Leerzeilen, Leerzeichen und Tabstoppzeichen

Leere Zeilen signalisieren auch das Ende eines Blocks in Markdown.

• Platzieren Sie ein einzelnes Leerzeichen zwischen Markdown-Blöcken unterschiedlicher Typen; Beispiel: zwischen einem Absatz und einer Liste oder Kopfzeile.
• Verwenden Sie nicht mehr als eine leere Zeile. Mehrere leere Zeilen werden als einzelne leere Zeile in HTML gerendert, daher sind die zusätzlichen leeren Zeilen unnötig.
• Verwenden Sie nicht mehrere aufeinander folgende Leere Zeilen in einem Codeblock, und aufeinander folgende Leerzeilen unterbrechen den Codeblock.

Abstände sind in Markdown wichtig.

• Entfernen Sie zusätzliche Leerzeichen am Zeilenende. Nachgestellte Leerzeichen können sich auf das Rendern von Markdown auswirken.
• Verwenden Sie immer Leerzeichen anstelle von Tabs (harte Tabs).

Titel und Überschriften

Verwenden Sie ATX-Überschriften nur (#-Format, im Gegensatz zu =- oder --Formatüberschriften).

• Verwenden Sie die Satzgroßschreibung – nur Eigennamen und der erste Buchstabe eines Titels oder einer Kopfzeile werden großgeschrieben.
• Einfügen eines einzelnen Leerzeichens zwischen dem # und dem ersten Buchstaben der Überschrift
• Überschriften mit einer Leerzeile umgeben
• Verwenden Sie nicht mehr als ein H1 pro Dokument.
  • Dies sollte die erste Kopfzeile sein
  • Er sollte mit dem Titel des Artikels übereinstimmen.
• Erhöhen Sie die Kopfzeilenebenen um eine Ebene – überspringen Sie keine Ebenen.
• Tiefe auf H3 oder H4 beschränken
• Vermeiden Sie die Verwendung von fettgedruckter Schrift oder anderen Markierungen in Überschriften.

Zeilenlänge auf 100 Zeichen beschränken

Beschränken Sie für konzeptionelle Artikel und Cmdlet-Verweise Zeilen auf 100 Zeichen. Beschränken about_ Sie für Artikel die Zeilenlänge auf 79 Zeichen. Das Beschränken der Zeilenlänge verbessert die Lesbarkeit von git-Diffs und -Verlauf. Es erleichtert auch anderen Autoren, Beiträge zu leisten.

Verwenden Sie die Erweiterung "Reflow Markdown " in VS Code, um Absätze so umzubrechen, dass sie der vorgeschriebenen Zeilenlänge entsprechen.

Einige Inhaltstypen können nicht einfach dynamisch umbrochen werden. Beispielsweise kann es, abhängig vom Inhalt und der Codesprache, auch schwierig sein, den Code innerhalb von Codeblöcken dynamisch umzubrechen. Bei Tabellen ist kein dynamischer Umbruch möglich. Verwenden Sie in diesen Fällen Ihr bestes Urteil, um den Inhalt so nah wie möglich an der Grenze von 100 Zeichen zu halten.

Betonung

Zur Hervorhebung unterstützt Markdown fett und kursiv. Mit Markdown können Sie * oder _ verwenden, um die Hervorhebung zu markieren. Um jedoch konsistent zu sein und Absichten anzuzeigen:

• Verwenden Sie ** für Fettformatierung.
• Verwende _ für Kursivschrift

Das Folgen dieses Musters erleichtert es anderen Benutzern, die Absicht des Markups zu verstehen, wenn es eine Mischung aus Fett und Kursiv in einem Dokument gibt.

Listet

Wenn Ihre Liste mehrere Sätze oder Absätze enthält, sollten Sie eine Kopfzeile auf Unterebene anstelle einer Liste verwenden.

Fügen Sie um Listen eine einzelne leere Zeile ein.

Unsortierte Listen

• Beenden Sie Listenelemente nicht mit einem Punkt, es sei denn, sie enthalten mehrere Sätze.
• Verwenden Sie den Bindestrich (-) als Aufzählungszeichen für Listenelemente, um eine Verwechslung mit dem Hervorhebungs-Markup zu vermeiden, das das Sternchen (*) verwendet.
• Um einen Absatz oder andere Elemente unter einem Aufzählungselement einzuschließen, fügen Sie einen Zeilenumbruch ein, und richten Sie den Einzug am ersten Zeichen nach dem Aufzählungszeichen aus.

Beispiel:

This is a list that contains child elements under a bullet item.

- First bullet item

  Sentence explaining the first bullet.

  - Child bullet item

    Sentence explaining the child bullet.

- Second bullet item
- Third bullet item

Dies ist eine Liste, die Unterelemente unter einem Aufzählungselement enthält.

• Erstes Aufzählungselement

  Satz zur Erläuterung des ersten Aufzählungselements.

  • Untergeordnetes Aufzählungselement

    Satz zur Erläuterung des untergeordneten Aufzählungselements.

• Zweites Aufzählungselement

• Drittes Aufzählungselement

Sortierte Listen

• Alle Elemente in einer nummerierten Liste sollten die Nummer 1. verwenden, anstatt jedes Element zu erhöhen.
  • Markdown-Rendering erhöht den Wert automatisch.
  • Dadurch wird die Neuanordnung von Elementen vereinfacht und der Einzug von untergeordnetem Inhalt standardisiert.
• Um einen Absatz oder andere Elemente unter einem nummerierten Aufzählungselement einzuschließen, richten Sie den Einzug am ersten Zeichen nach der Elementnummer aus.

Beispiel:

1. For the first element, insert a single space after the `1`. Long sentences should be wrapped to
   the next line and must line up with the first character after the numbered list marker.

   To include a second element, insert a line break after the first and align indentations. The
   indentation of the second element must line up with the first character after the numbered list
   marker.

1. The next numbered item starts here.

Das resultierende Markdown wird wie folgt gerendert:

1. Fügen Sie für das erste Element ein einzelnes Leerzeichen hinter dem 1. Lange Sätze sollten in die nächste Zeile umbrochen werden und müssen am ersten Zeichen hinter dem nummerierten Listenmarker ausgerichtet werden.

   Um ein zweites Element aufzuführen, fügen Sie nach dem ersten Element einen Zeilenumbruch ein, und richten Sie die Einzüge aus. Der Einzug des zweiten Elements muss am ersten Zeichen hinter dem nummerierten Listenmarker ausgerichtet werden.

2. Das nächste nummerierte Element beginnt hier.

Bilder

Die Syntax zum Einschließen eines Bilds lautet:

![[alt text]](<folderPath>)

Example:
![Introduction](./media/overview/Introduction.png)

Dabei alt text handelt es sich um eine kurze Beschreibung des Bilds und <folderPath> um einen relativen Pfad zum Bild.

• Alternativtext ist für die Unterstützung der Sprachausgabe für Personen mit eingeschränktem Sehvermögen erforderlich.
• Bilder sollten in einem media/<article-name> Ordner innerhalb des Ordners gespeichert werden, der den Artikel enthält.
  • Erstellen Sie einen Ordner, der dem Dateinamen Ihres Artikels unter dem media Ordner entspricht. Kopieren Sie die Bilder für diesen Artikel in diesen neuen Ordner.
• Teilen Sie keine Bilder zwischen Artikeln.
  • Wenn ein Bild von mehreren Artikeln verwendet wird, muss jeder Ordner über eine Kopie dieses Bilds verfügen.
  • Dadurch wird verhindert, dass sich eine Änderung an einem Bild in einem Artikel auf einen anderen Artikel auswirkt.

Die folgenden Bilddateitypen werden unterstützt: *.png, *.gif, *.jpeg, , *.jpg*.svg

Markdown-Erweiterung – Warnungsfelder

Das Lernerstellungspaket enthält Tools, die Funktionen unterstützen, die einzigartig für unser Veröffentlichungssystem sind. Warnungen sind eine Markdown-Erweiterung zum Erstellen von Blockquotes, die mit Farben und Symbolen gerendert werden, die die Bedeutung des Inhalts hervorheben. Die folgenden Warnungstypen werden unterstützt:

> [!NOTE]
> Information the user should notice even if skimming.

> [!TIP]
> Optional information to help a user be more successful.

> [!IMPORTANT]
> Essential information required for user success.

> [!CAUTION]
> Negative potential consequences of an action.

> [!WARNING]
> Dangerous certain consequences of an action.

Diese Warnungen sehen in Microsoft Learn wie folgt aus:

Hinweisblock

Hinweis

Informationen, die der Benutzer selbst beim Durchblättern bemerken sollte.

Tipp-Block

Tipp

Optionale Informationen, die einem Benutzer helfen sollen, erfolgreicher zu sein.

Wichtiger Block

Von Bedeutung

Wichtige Informationen, die für den Erfolg des Benutzers erforderlich sind.

Achtung-Block

Vorsicht

Negative mögliche Folgen einer Aktion.

Warnungs-Block

Warnung

Bestimmte Folgen einer Aktion sind gefährlich.

Markdown-Erweiterung – Tabellen

Tabellen sind Anordnungen von Daten, die aus Zeilen und Spalten bestehen:

• Eine einzelne Kopfzeilenreihe
• Eine Trennzeichenzeile, die die Kopfzeile von den Daten trennt
• Null oder mehr Datenzeilen

Jede Zeile besteht aus Zellen, die beliebigen Text enthalten, der durch Rohre (|) getrennt ist. Für eine bessere Übersichtlichkeit wird auch ein führender und nachfolgender senkrechter Strich empfohlen. Leerzeichen zwischen senkrechten Strichen und Zellinhalten werden gekürzt. Elemente auf Blockebene können nicht in eine Tabelle eingefügt werden. Der gesamte Inhalt einer Zeile muss sich in einer einzelnen Zeile befinden.

Die Trennzeile besteht aus Zellen, deren einziger Inhalt Bindestriche (-) und optional ein führender und/oder nachfolgender Doppelpunkt (:) sind, um für die Ausrichtung links, rechts oder zentriert anzugeben.

Für kleine Tabellen sollten Sie stattdessen eine Liste verwenden. Für Listen gilt:

• Einfacher zu verwalten und zu lesen
• Sie können dynamisch so umgebrochen werden, dass sie in die Zeilenbegrenzung von 100 Zeichen passen.
• Sie sind barrierefreier für Benutzer, die eine Sprachausgabe zur Unterstützung verwenden.

Weitere Informationen finden Sie im Abschnitt "Tabellen" der Markdown-Referenz für Microsoft Learn.

Links

• Hyperlinks müssen die Markdown-Syntax [friendlyname](url-or-path)verwenden.

• Das Veröffentlichungssystem unterstützt drei Arten von Links:

  • URL-Links
  • Dateilinks
  • Querverweislinks

• Alle URLs für externe Websites sollten HTTPS verwenden, es sei denn, dies ist für die Zielwebsite nicht gültig.

• Links müssen über einen Anzeigenamen verfügen, normalerweise der Titel des verknüpften Themas.

• Verwenden Sie innerhalb der Klammern eines Links keine Graviszeichen oder fette oder sonstige Auszeichnung.

• Reine URLs können verwendet werden, wenn Sie einen bestimmten URI dokumentieren, müssen aber in Graviszeichen eingeschlossen werden. Beispiel:

  By default, if you don't specify this parameter, the DMTF standard resource URI
  `http://schemas.dmtf.org/wbem/wscim/1/cim-schema/2/` is used and the class name is appended to it.
  

• Verwenden Sie Linkverweise , sofern zulässig. Verknüpfungsverweise innerhalb von Absätzen machen die Absätze besser lesbar.

  Verknüpfungsverweise unterteilen einen Markdown-Link in zwei Teile:

  • der Linkverweis – [friendlyname][id]
  • die Verknüpfungsdefinition - [id]: url-or-path

Links vom URL-Typ

• URL-Links zu anderen Artikeln auf learn.microsoft.com müssen website-relative Pfade verwenden. Der einfachste Weg, einen websiterelativen Link zu erstellen, 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 Markdown einfügen.
• Schließen Sie keine Gebietsschemas in URLs für Microsoft-Eigenschaften (/en-us aus URL entfernen) oder Wikipedia-Links ein.
• Entfernen Sie alle unnötigen Abfrageparameter aus der URL. Beispiele, die entfernt werden sollten:
  • ?view=powershell-5.1 – Wird verwendet, um eine Verknüpfung mit einer bestimmten Version von PowerShell zu erstellen.
  • ?redirectedfrom=MSDN – der URL hinzugefügt, wenn Sie von einem alten Artikel an den neuen Speicherort umgeleitet werden
• Wenn Sie eine Verknüpfung mit einer bestimmten Version eines Dokuments herstellen müssen, müssen Sie den &preserve-view=true Parameter zur Abfragezeichenfolge hinzufügen. Beispiel: ?view=powershell-5.1&preserve-view=true
• Auf Microsoft-Websites enthalten URL-Links keine Dateierweiterungen (z. B. nein .md)

Dateilinks

• Eine Dateiverknüpfung wird verwendet, um von einem Referenzartikel zu einem anderen oder von einem konzeptionellen Artikel zu einem anderen in demselben Dokument zu verknüpfen.
  • Wenn Sie einen Link von einem konzeptionellen Artikel zu einem Referenzartikel erstellen müssen, müssen Sie einen URL-Link verwenden.
  • Wenn Sie einen Link zu einem Artikel in einem anderen Dokument oder repositoryübergreifend erstellen müssen, müssen Sie einen URL-Link verwenden.
• Relative Dateipfade verwenden (z. B.: ../folder/file.md)
• Alle Dateipfade verwenden Schrägstriche (/)
• Dateierweiterung einschließen (z. B .md. )

Querverweislinks

Querverweislinks sind ein spezielles Feature, das vom Veröffentlichungssystem unterstützt wird. Sie können Querverweislinks in konzeptionellen Artikeln verwenden, um eine Verknüpfung mit .NET-API oder Cmdlet-Referenz zu erstellen.

• Links zur .NET-API-Referenz finden Sie unter Verwenden von Links in der Dokumentation im zentralen Mitwirkendenhandbuch.

• Links zum Cmdlet-Verweis weisen das folgende Format auf: xref:<module-name>.<cmdlet-name>. Um beispielsweise eine Verknüpfung mit dem Get-Content Cmdlet im Modul "Microsoft.PowerShell.Management " zu erstellen.

  [Get-Content](xref:Microsoft.PowerShell.Management.Get-Content)

Deep Linking

Deep-Verknüpfungen sind sowohl für URL- als auch Dateilinks zulässig.

• Der Ankertext muss klein geschrieben sein.
• Fügen Sie den Anker am Ende des Zielpfads hinzu. Beispiel:
  • [about_Splatting](about_Splatting.md#splatting-with-arrays)
  • [custom key bindings](https://code.visualstudio.com/docs/getstarted/keybindings#_custom-keybindings-for-refactorings)

Weitere Informationen finden Sie unter Verwenden von Links in der Dokumentation.

Codespannen

Codespannen werden für Inlinecodeausschnitte innerhalb eines Absatzes verwendet. Verwenden Sie einzelne Graviszeichen, um eine Codespanne anzugeben. Beispiel:

PowerShell cmdlet names use the `Verb-Noun` naming convention.

Dieses Beispiel wird wie folgt dargestellt:

PowerShell-Cmdletnamen verwenden die Verb-Noun Benennungskonvention.

Codeblöcke

Codeblöcke werden für Befehlsbeispiele, mehrzeilige Codebeispiele, Abfragesprachen und Ausgaben verwendet. Es gibt zwei Möglichkeiten, einen Textabschnitt in einer Artikeldatei als Codeblock anzugeben: durch das Einschließen in Dreifach-Graviszeichen (```) oder durch Einrücken.

Verwenden Sie niemals Einrückungen, da hier leicht Fehler gemacht werden können und es für einen anderen Autor schwierig sein kann, Ihre Absicht zu verstehen, wenn er Ihren Artikel bearbeitet.

Eingezäunte Codeblöcke können ein optionales Tag enthalten, das die im Block enthaltene Sprachsyntax angibt. Die Veröffentlichungsplattform unterstützt eine Liste von Sprachtags. Der Sprach-Tag wird verwendet, um Syntaxhervorhebung bereitzustellen, wenn der Artikel auf der Webseite gerendert wird. Beim Sprach-Tag wird die Groß- und Kleinschreibung nicht beachtet; Sie sollten jedoch, mit Ausnahme einiger Sonderfälle, Kleinbuchstaben verwenden.

• Codezäune ohne Tags können für Syntaxblöcke oder andere Inhaltstypen verwendet werden, bei denen syntaxmarkierung nicht erforderlich ist.
• Verwenden Sie beim Anzeigen der Ausgabe eines Befehls einen markierten Codezaun mit dem Sprachtag Output. Das gerenderte Feld ist als Ausgabe bezeichnet und weist keine Syntaxmarkierung auf.
• Wenn sich die Ausgabe in einer bestimmten unterstützten Sprache befindet, verwenden Sie das entsprechende Sprachkennzeichen. Beispielsweise geben viele Befehle JSON aus, also verwenden Sie das json Tag.
• Wenn Sie ein nicht unterstütztes Sprachtag verwenden, wird der Codeblock ohne Syntaxmarkierung gerendert. Der Sprach-Tag wird als Beschriftung für das gerenderte Codefeld auf der Webseite verwendet. Schreiben Sie den Tag mit einem Großbuchstaben, sodass die Bezeichnung auf der Webseite großgeschrieben wird.

Nächste Schritte

PowerShell-Formatanleitung