Anleitung zum Schreiben in Markdown

Die Basis für MDN Markdown ist GitHub-Flavored Markdown (GFM): https://github.github.com/gfm/. Das bedeutet, dass Sie sich auf die GFM-Spezifikation beziehen können für alles, was in dieser Seite nicht ausdrücklich festgelegt ist. GFM ist wiederum eine Obermenge von CommonMark (https://spec.commonmark.org/).

Die GFM-Spezifikation definiert zwei grundlegende Arten von Links:

• Inline-Links, bei denen das Ziel direkt nach dem Linktext angegeben wird.
• Referenz-Links, bei denen das Ziel an anderer Stelle im Dokument definiert ist.

Auf MDN erlauben wir nur Inline-Links. Dies ist der richtige Weg, um GFM-Links auf MDN zu schreiben:

[Macarons](https://en.wikipedia.org/wiki/Macaron) are delicious but tricky to make.

Dies ist ein falscher Weg, um Links auf MDN zu schreiben:

[Macarons][macaron] are delicious but tricky to make.

[macaron]: https://en.wikipedia.org/wiki/Macaron

In GFM und CommonMark können Autoren "Code-Zäune" verwenden, um <pre>-Blöcke zu kennzeichnen. Der öffnende Code-Zaun kann von einem Text gefolgt werden, der als "Info-String" bezeichnet wird. Die Sprache des Codebeispiels muss unter Verwendung des ersten Wortes des Info-Strings festgelegt werden, und dies wird verwendet, um Syntax-Highlighting für den Block bereitzustellen. Die folgenden Wörter werden unterstützt:

• Programmiersprachen
  • JavaScript
    • js - JavaScript
    • ts - TypeScript
    • jsx - React JSX
    • tsx - React TSX
  • C-ähnlich
    • c - C
    • cpp - C++
    • cs - C#
    • java - Java
  • Andere
    • python - Python
    • php - PHP
    • rust - Rust
    • glsl - GLSL (OpenGL Shaders)
    • sql - SeQueL-Befehle
    • wat - WebAssembly
    • webidl - Web Interface Definition Language
• Styling
  • css - CSS
  • scss - Sass (SCSS)
  • less - Less
• Markup
  • html - HTML
  • svg - SVG
  • xml - XML
  • mathml - MathML
  • md - Markdown
  • latex - LaTeX
• Eingabeaufforderungen
  • bash - Bash/Shell
  • batch - Batch (Windows Shell)
  • powershell - PowerShell
• Konfigurations-/Datendateien
  • json - JSON
  • ini - INI
  • yaml - YAML
  • toml - TOML
  • sql - SQL-Datenbank
  • ignore - Gitignore-Datei
  • apacheconf - Apache-Konfiguration
  • nginx - NGINX-Konfiguration
• Vorlagen
  • django - Django-Vorlagen
  • svelte - Svelte-Vorlagen
  • hbs - Handlebars-Vorlagen
  • pug - Pug-Vorlagen (die möglicherweise von Express verwendet werden)
• Andere
  • plain - Einfacher Text
  • diff - Diff-Datei
  • http - HTTP-Header
  • regex - Regex
  • uri - URIs und URLs

Zum Beispiel:

```js
const greeting = "I will get JavaScript syntax highlighting";
```

Wenn das gewünschte Highlighting nicht in der Liste aufgeführt ist, sollten Sie den Codeblock als plain markieren. Zusätzliche Sprachen können im Prozess auf GitHub besprochen angefordert werden.

Autoren können ein -nolint-Suffix zu jeder der Sprachkennungen hinzufügen:

```html-nolint
<p>
I will not be linted.
</p>
```

Solche Codeblöcke erhalten das entsprechende Syntax-Highlighting und werden vom Live-Beispielsystel erkannt, aber von Lintern oder automatischen Formatierern wie Prettier ignoriert. Autoren sollten dieses Suffix verwenden, um ungültigen Code oder alternative Formatierung darzustellen, die Linter oder Formatter nicht beheben sollten.

GFM unterstützt Info-Strings, mit denen Autoren zusätzliche Informationen zu einem Codeblock angeben können. Auf MDN werden Info-Strings in Klassennamen umgewandelt.

Autoren können einen der folgenden Info-Strings angeben:

• example-good: Dieses Beispiel als ein gutes Beispiel (nachzuahmen) gestalten
• example-bad: Dieses Beispiel als ein schlechtes Beispiel (zu vermeiden) gestalten
• hidden: Diesen Codeblock auf der Seite nicht rendern. Dies ist für die Verwendung in Live-Beispielen.

Zum Beispiel:

```js example-good
const greeting = "I'm a good example";
```

```js example-bad
const greeting = "I'm a bad example";
```

```js hidden
const greeting = "I'm a secret greeting";
```

Diese werden wie folgt gerendert:

const greeting = "I'm a good example";

const greeting = "I'm a bad example";

Dieses Problem wurde gelöst in:

• https://github.com/mdn/content/issues/3512
• https://github.com/mdn/yari/pull/7017

Autoren können die GFM-Alerts-Syntax verwenden, um besondere Aufmerksamkeit auf Inhalte zu lenken. Es gibt drei Arten von Alerts: Hinweise, Warnungen und Hinweise.

• Um einen Hinweis hinzuzufügen, erstellen Sie ein Blockzitat, dessen erste Zeile [!NOTE] ist.
• Um eine Warnung hinzuzufügen, erstellen Sie ein Blockzitat, dessen erste Zeile [!WARNING] ist.
• Um einen Hinweis hinzuzufügen, erstellen Sie ein Blockzitat, dessen erste Zeile [!CALLOUT] ist.

Hinweise und Warnungen fügen dem Anfang der Ausgabe ein lokalisiertes Hinweis: oder Warnung: hinzu, während Hinweise dies nicht tun. Dies macht Hinweise zu einer guten Wahl, wenn ein Autor einen benutzerdefinierten Titel bereitstellen möchte.

Mehrere Zeilen werden durch eine leere Blockzitatzeile auf die gleiche Weise wie normale Absätze erzeugt. Darüber hinaus werden mehrere Zeilen ohne Leerzeichen wie normale Markdown-Zeilen behandelt und verketten.

Das Blockzitat kann Codeblöcke oder andere Blockelemente enthalten.

Hinweis

> [!NOTE]
> This is how you write a note.
>
> It can have multiple lines.

Dies wird das folgende HTML erzeugen:

<div class="notecard note">
  <p><strong>Note:</strong> This is how you write a note.</p>
  <p>It can have multiple lines.</p>
</div>

Dieses HTML wird als hervorgehobenes Feld gerendert:

Warnungen

> [!WARNING]
> This is how you write a warning.
>
> It can have multiple paragraphs.

Dies wird das folgende HTML erzeugen:

<div class="notecard warning">
  <p><strong>Warning:</strong> This is how you write a warning.</p>
  <p>It can have multiple paragraphs.</p>
</div>

Dieses HTML wird als hervorgehobenes Feld gerendert:

Hinweise

> [!CALLOUT]
>
> **This is how you write a callout.**
>
> It can have multiple paragraphs.

Dies wird das folgende HTML erzeugen:

<div class="callout">
  <p><strong>This is how you write a callout.</strong></p>
  <p>It can have multiple paragraphs.</p>
</div>

Dieses HTML wird als hervorgehobenes Feld gerendert:

Hinweis mit einem Codeblock

Dieses Beispiel enthält einen Codeblock.

> [!NOTE]
> This is how you write a note.
>
> It can contain code blocks.
>
> ```js
> const s = "I'm in a code block";
> ```
>
> Like that.

Dies wird das folgende HTML erzeugen:

<div class="notecard note">
  <p><strong>Note:</strong> This is how you write a note.</p>
  <p>It can contain code blocks.</p>
  <pre class="brush: js">const s = "I'm in a code block";</pre>
  <p>Like that.</p>
</div>

Dieses HTML wird als mit einem Codeblock gerendert:

const s = "I'm in a code block";

Dieses Problem wurde gelöst in https://github.com/mdn/content/issues/3483.

Definitionslisten werden häufig auf MDN verwendet, aber von GFM nicht unterstützt. MDN führt ein benutzerdefiniertes Format für Definitionslisten ein, das eine modifizierte Form einer GFM ungeordneten Liste (<ul>) ist. In diesem Format:

• Das GFM <ul> enthält eine beliebige Anzahl von GFM <li>-Elementen auf oberster Ebene.
• Jedes dieser GFM <li>-Elemente auf oberster Ebene muss als letztes Element ein GFM <ul>-Element enthalten.
• Dieses letzte verschachtelte <ul> muss ein einziges GFM <li>-Element enthalten, dessen Textinhalt mit ": " beginnt (ein Doppelpunkt gefolgt von einem Leerzeichen). Dieses Element kann Blockelemente enthalten, einschließlich Absätzen, Codeblöcken, eingebetteten Listen und Hinweisen.

Jedes dieser GFM <li>-Elemente auf oberster Ebene wird in ein <dt>/<dd>-Paar umgewandelt, wie folgt:

• Das GFM <li>-Element auf oberster Ebene wird als GFM <li>-Element analysiert, und sein interner Inhalt wird den Inhalt des <dt> darstellen, mit Ausnahme des letzten verschachtelten <ul>, das nicht in das <dt> einbezogen wird.
• Das <li>-Element im letzten verschachtelten <ul> wird als GFM <li>-Element analysiert, und sein interner Inhalt wird den Inhalt des <dd> darstellen, mit Ausnahme des führenden ": ", das verworfen wird.

Zum Beispiel, dies ist ein <dl>:

- term1
  - : My description of term1
- `term2`

  - : My description of term2

    It can have multiple paragraphs, and code blocks too:

    ```js
    const thing = 1;
    ```

In GFM/CommonMark würde dies das folgende HTML erzeugen:

<ul>
  <li>
    <p>term1</p>
    <ul>
      <li>: My description of term1</li>
    </ul>
  </li>
  <li>
    <p><code>term2</code></p>
    <ul>
      <li>
        <p>: My description of term2</p>
        <p>It can have multiple paragraphs, and code blocks too:</p>
        <pre>
          <code class="brush: js">const thing = 1;</code>
        </pre>
      </li>
    </ul>
  </li>
</ul>

Auf MDN würde dies das folgende HTML erzeugen:

<dl>
  <dt>
    <p>term1</p>
  </dt>
  <dd>My description of term1</dd>
  <dt>
    <p><code>term2</code></p>
  </dt>
  <dd>
    <p>My description of term2</p>
    <p>It can have multiple paragraphs, and code blocks too:</p>
    <pre>
       <code class="brush: js">const thing = 1;</code>
    </pre>
  </dd>
</dl>

Definitionslisten, die mit dieser Syntax geschrieben wurden, müssen aus Paaren von <dt>/<dd>-Elementen bestehen. Es ist nicht möglich, mit dieser Syntax eine Liste mit mehr als einem aufeinander folgenden <dt>-Element oder mehr als einem aufeinander folgenden <dd>-Element zu schreiben: der Parser behandelt dies als Fehler. Wir erwarten, dass fast alle Definitionslisten auf MDN mit dieser Einschränkung funktionieren, und für die, die dies nicht tun, können Autoren auf Roh-HTML zurückgreifen.

Dies ist nicht erlaubt:

- `param1`, `param2`, `param3`
  - : My description of `param1`
  - : My description of `param2`
  - : My description of `param3`

Als Workaround für Fälle, in denen ein Autor mehrere <dt>-Elemente mit einem einzigen <dd>-Element verknüpfen muss, kann erwogen werden, diese als ein einziges <dt> bereitzustellen, das mehrere Begriffe enthält, getrennt durch Kommas, wie folgt:

- `param1`, `param2`, `param3`
  - : My description of params 1, 2, and 3

Der Grund für die hier beschriebene Syntax ist, dass sie gut mit Tools funktioniert, die CommonMark erwarten (zum Beispiel Prettier oder GitHub-Previews), während sie sich relativ einfach schreiben und parsen lässt.

Dieses Problem wurde gelöst in https://github.com/mdn/content/issues/4367.

GFM bietet eine Syntax zum Erstellen von Tabellen, die wir auf MDN nutzen. Es gibt jedoch Zeiten, in denen GFM-Tabellen nicht unseren Anforderungen entsprechen:

• Die GFM-Syntax unterstützt nur einen Teil der in HTML verfügbaren Funktionen. Wenn Sie Tabellenfunktionen verwenden müssen, die in GFM nicht unterstützt werden, verwenden Sie HTML für die Tabelle.
• Wenn die GFM-Darstellung der Tabelle mehr als 150 Zeichen breit wäre, verwenden Sie HTML für die Tabelle.
• Wir unterstützen eine spezielle Art von Tabelle, die als "Eigenschaftstabelle" bezeichnet wird und immer HTML ist.

Das allgemeine Prinzip ist, dass Autoren die GFM-Markdown-Syntax verwenden sollten, wenn sie können, und auf Roh-HTML zurückgreifen sollten, wenn sie müssen oder wenn HTML lesbarer ist. Weitere Informationen finden Sie unter Wann HTML-Tabellen verwenden.

In der GFM-Tabellen-Syntax können Autoren führende und abschließende Pipes für Zeilen weglassen. Aus Gründen der Lesbarkeit müssen MDN-Autoren jedoch diese Pipes einschließen. Außerdem müssen Autoren in den Zeilen abschließende Leerzeichen bereitstellen, sodass alle Zellen in einer Spalte im Klartext gleich lang sind.

Das heißt, MDN-Autoren müssen diesen Stil verwenden:

| Heading 1 | Heading 2 | Heading 3 |
| --------- | --------- | --------- |
| cell 1    | cell 2    | cell 3    |
| cell 4    | cell 5    | cell 6    |

und nicht diesen Stil:

| Heading 1 | Heading 2 | Heading 3 |
| --------- | --- |----------------------|
| cell 1 | cell 2 | cell 3 |
cell 4 | cell 5 | cell 6

Tabellen werden von Prettier formatiert, sodass Autoren auf Tools zurückgreifen, um Tabellen ordnungsgemäß zu formatieren.

Es gibt drei Hauptumstände, unter denen Autoren HTML-Tabellen anstelle der GFM-Syntax verwenden sollten:

1. Die Tabelle verwendet Funktionen, die in GFM nicht unterstützt werden (siehe unten).
2. Die GFM-Tabelle wäre zu breit, um lesbar zu sein.
3. Der Autor möchte eine spezielle Art von Tabelle, die als "Eigenschaftstabelle" bezeichnet wird.

Tabelleneigenschaften, die in GFM nicht unterstützt werden

Die Hauptbeschränkungen der GFM-Tabellensyntax sind:

• GFM-Tabellen müssen eine Kopfzeile haben.
• GFM-Tabellen dürfen keine Kopfspalte haben.
• GFM verarbeitet keine GFM-Blockelemente in Tabellenzellen. Zum Beispiel können Sie keine Liste in einer Tabellenzelle haben.
• GFM-Tabellen können keine Klassen zugewiesen werden.
• GFM unterstützt keine anderen Tabellenelemente als <table>, <tr>, <th> und <td>.
• GFM unterstützt keine Tabellenattribut wie colspan, rowspan oder scope.

Wenn ein Autor eine der nicht unterstützten Funktionen verwenden muss, sollte er die Tabelle in HTML schreiben.

Beachten Sie, dass wir die allgemeine Verwendung von <caption>-Elementen auf Tabellen nicht empfehlen, da dies auch die GFM-Syntax ausschließen würde.

Maximale Breite von GFM-Tabellen

Selbst wenn eine Tabelle in GFM geschrieben werden könnte, ist es manchmal besser, HTML zu verwenden, da GFM einen "ASCII-Kunst"-Ansatz für Tabellen verwendet, der nicht lesbar ist, wenn Tabellenzeilen lang werden. Betrachten Sie die folgende Tabelle:

<table>
  <tr>
    <th>A heading 1</th>
    <th>A heading 2</th>
    <th>A heading 3</th>
    <th>A heading 4</th>
    <th>A heading 5</th>
    <th>A heading 6</th>
  </tr>
  <tr>
    <td>Something shortish</td>
    <td>
      Something much longer that really goes into a lot of detail about
      something, so much so that the table formatting starts to look bad in GFM
      format.
    </td>
    <td>Something shortish</td>
    <td>
      Another cell with lots of text in it, that also really goes into a lot of
      detail about something, so much so that the table formatting starts to
      look bad in GFM format.
    </td>
    <td>Something shortish</td>
    <td>Something shortish</td>
  </tr>
</table>

In GFM sieht dies so aus:

| A heading 1        | A heading 2                                                                                                                                         | A heading 3        | A heading 4                                                                                                                                                              | A heading 5        | A heading 6        |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------------------ |
| Something shortish | Something much longer that really goes into a lot of detail about something, so much so that the table formatting starts to look bad in GFM format. | Something shortish | Another cell with lots of text in it, that also really goes into a lot of detail about something, so much so that the table formatting starts to look bad in GFM format. | Something shortish | Something shortish |

In einem solchen Fall wäre es besser, HTML zu verwenden.

Dies führt zu der folgenden Richtlinie: Wenn die Markdown-Darstellung der Tabelle mehr als 150 Zeichen breit wäre, verwenden Sie HTML für die Tabelle.

Eigenschaftstabellen

Eigenschaftstabellen sind eine spezifische Art von Tabelle, die zum Anzeigen von strukturierten Eigenschaft-Wert-Inhalten auf einer Reihe von Seiten eines bestimmten Typs verwendet wird. Diese Tabellen haben zwei Spalten: die erste Spalte ist die Kopfspalte und listet die Eigenschaften auf, und die zweite Spalte listet ihre Werte für dieses bestimmte Element auf. Hier ist zum Beispiel die Eigenschaftstabelle für das PannerNode-Interface:

Diese Seiten können nicht in GFM dargestellt werden, da sie eine Kopfspalte haben, daher sollten Autoren in diesem Fall HTML verwenden. Um das spezielle Styling zu erhalten, sollten Autoren die "properties"-Klasse auf die Tabelle anwenden:

<table class="properties"></table>

Dieses Problem wurde gelöst in https://github.com/mdn/content/issues/4325, https://github.com/mdn/content/issues/7342, und https://github.com/mdn/content/issues/7898#issuecomment-913265900.

Autoren können die HTML <sup>- und <sub>-Elemente verwenden, falls erforderlich, sollten jedoch nach Möglichkeit Alternativen verwenden. Insbesondere:

• Für Exponentialdarstellung nutzen Sie das Caret: 2^53.
• Für Ordnungsarten wie 1^st bevorzugen Sie Wörter wie "erster".
• Für Fußnoten markieren Sie die Fußnotenzitate nicht, z.B. <sup>[1]</sup>.

Dieses Problem wurde gelöst in https://github.com/mdn/content/issues/4578.

Die Seitenübersicht ist der erste "Inhalt"-Absatz einer Seite—der erste Text, der nach der Seite-Metadatenvorlage und allen Seitenleisten oder Seitenbannern Makros erscheint.

Diese Zusammenfassung wird für Suchmaschinenoptimierung (SEO) genutzt und auch automatisch zusammen mit Seitenlisten durch einige Makros eingebunden. Der erste Absatz sollte daher sowohl prägnant als auch informativ sein.

Dieses Problem wurde gelöst in https://github.com/mdn/content/issues/3923.

Autoren verwenden Makros im Text, um geläufige Verlinkungsmuster zu templaten oder um spezifische Code- oder Textblöcke einzubinden:

The **`margin`** [CSS](/en-US/docs/Web/CSS) property sets the margin area on all four sides of an element.
It is a shorthand for {{cssxref("margin-top")}}, {{cssxref("margin-right")}}, {{cssxref("margin-bottom")}}, and {{cssxref("margin-left")}}.
…

Siehe Verwendung von Makros für weitere Informationen.