Anleitung zum Schreiben in Markdown

Die Grundlage für MDN Markdown ist GitHub-Flavored Markdown (GFM): https://github.github.com/gfm/. Das bedeutet, dass Sie sich an die GFM-Spezifikation halten können für alles, was nicht ausdrücklich auf dieser Seite spezifiziert wird. 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.
• reference links, bei denen das Ziel an anderer Stelle im Dokument definiert wird.

Auf MDN erlauben wir nur Inline-Links.

Dies ist die korrekte Art, GFM-Links auf MDN zu schreiben:

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

Dies ist eine inkorrekte Art, 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 fences" verwenden, um <pre>-Blöcke abzugrenzen. Der eröffnende Code fence kann von einem Text gefolgt werden, der als "info string" bezeichnet wird. Die Spezifikation besagt Folgendes:

Das erste Wort des Info-Strings wird typischerweise verwendet, um die Sprache des Codesamples anzugeben und im class-Attribut des Codetags gerendert.

Es ist erlaubt, dass der Info-String mehrere Wörter enthält, wie zum Beispiel:

```fee fi fo fum
// some example code
```

Bei MDN verwenden Autoren Code fences für Beispiel-Codeblöcke. Sie müssen die Sprache des Codesamples mit dem ersten Wort des Info-Strings angeben, und dies wird verwendet, um Syntaxhervorhebungen 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-Kommandos
    • wasm - 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
• Kommandoeingaben
  • 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
  • handlebars - Handlebars-Vorlagen
  • pug - Pug-Vorlagen (die von Express verwendet werden können)
• Andere
  • plain - Klartext
  • diff - Diff-Datei
  • http - HTTP-Header
  • regex - Regex
  • uri - URIs und URLs

Zum Beispiel:

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

Wenn die gewünschte Hervorhebung nicht oben aufgeführt ist, sollten Sie den Codeblock als plain markieren. Zusätzliche Sprachen können im Prozess auf GitHub angefragt werden.

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

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

Codeblöcke wie dieser erhalten die entsprechende Syntaxhervorhebung und werden vom Live-Beispiels-System erkannt, aber sie werden von Lintern oder automatischen Formatierwerkzeugen wie Prettier ignoriert. Autoren sollten dieses Suffix verwenden, um ungültigen Code oder alternative Formatierungen anzuzeigen, die Linter oder Formatierer nicht beheben sollen.

GFM unterstützt info strings, die es Autoren ermöglichen, zusätzliche Informationen zu einem Codeblock bereitzustellen. Auf MDN werden Info-Strings in Klassennamen umgewandelt.

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

• example-good: dieses Beispiel als gutes Beispiel (dem man folgen sollte) stilisieren
• example-bad: dieses Beispiel als schlechtes Beispiel (das man vermeiden sollte) stilisieren
• hidden: diesen Codeblock auf der Seite nicht rendern. Dies ist für die Verwendung in Live-Beispielen bestimmt.

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 gerendert als:

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 aufmerksam auf Inhalte zu machen. Es gibt drei Arten von Hinweisen: Anmerkungen, Warnungen und Hinweiskästen.

• Um eine Anmerkung 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 Hinweiskasten hinzuzufügen, erstellen Sie ein Blockzitat, dessen erste Zeile [!CALLOUT] ist.

Anmerkungen und Warnungen fügen am Anfang der Ausgabe ein lokalisiertes Note: oder Warning: hinzu, während Hinweiskästen dies nicht tun. Dies macht Hinweiskästen zu einer guten Wahl, wenn ein Autor einen benutzerdefinierten Titel bereitstellen möchte.

Mehrere Zeilen werden durch eine leere Blockzitat-Zeile auf dieselbe Weise wie normale Absätze erzeugt. Außerdem werden mehrere Zeilen ohne Leerzeichen auch wie normale Markdown-Zeilen behandelt und zusammengefügt.

Das Blockzitat kann Codeblöcke oder andere Blockelemente enthalten.

Anmerkung

> [!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 ein 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 ein hervorgehobenes Feld gerendert:

Hinweiskästen

> [!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 ein hervorgehobenes Feld gerendert:

Anmerkung 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 mit einem Codeblock gerendert:

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

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

Definitionslisten werden bei MDN häufig verwendet, werden jedoch von GFM nicht unterstützt. MDN führt ein benutzerdefiniertes Format für Definitionslisten ein, das eine modifizierte Form von GFM-Unsortierten Listen (<ul>) ist. In diesem Format:

• Der GFM <ul> enthält beliebig viele Top-Level-GFM-<li>-Elemente.
• Jedes dieser Top-Level-GFM-<li>-Elemente muss als dessen finales Element ein GFM-<ul>-Element enthalten.
• Dieses finale verschachtelte <ul> muss ein einzelnes GFM-<li>-Element enthalten, dessen Textinhalt mit ": " beginnen muss (ein Doppelpunkt gefolgt von einem Leerzeichen). Dieses Element kann Blockelemente enthalten, einschließlich Absätze, Codeblöcke, eingebettete Listen und Anmerkungen.

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

• Das Top-Level-GFM-<li>-Element wird als GFM-<li>-Element geparst und dessen interner Inhalt wird den Inhalt des <dt> bilden, mit Ausnahme des finalen verschachtelten <ul>, das nicht im <dt> enthalten sein wird.
• Das <li>-Element im finalen verschachtelten <ul> wird als GFM-<li>-Element geparst und dessen interner Inhalt wird den Inhalt des <dd> bilden, mit Ausnahme des vorangestellten ": ", 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. Mit dieser Syntax ist es nicht möglich, eine Liste mit mehr als einem aufeinanderfolgenden <dt>-Element oder mehr als einem aufeinanderfolgenden <dd>-Element zu schreiben: der Parser wird dies als Fehler behandeln. Wir erwarten, dass fast alle Definitionslisten auf MDN mit dieser Einschränkung funktionieren, und für diejenigen, die dies nicht tun, können Autoren auf rohes 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, ziehen Sie in Betracht, diese als ein einzelnes <dt> bereitzustellen, das mehrere Begriffe enthält, die durch Kommas getrennt sind, wie dies:

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

Der Grund für die hier beschriebene Syntax ist, dass sie gut funktioniert mit Werkzeugen, die CommonMark erwarten (wie zum Beispiel Prettier oder GitHub-Vorschauen), während sie relativ einfach zu schreiben und zu parsen ist.

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

GFM bietet eine Syntax zur Erstellung von Tabellen, die wir in MDN verwenden. Es gibt jedoch Zeiten, in denen GFM-Tabellen nicht unseren Bedürfnissen entsprechen:

• Die GFM-Syntax unterstützt nur eine Teilmenge 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 "Eigenschaften-Tabelle" bezeichnet wird und eine eigene CSS-Klasse hat, weshalb sie immer HTML ist.

Das allgemeine Prinzip lautet, dass Autoren die GFM-Markdown-Syntax verwenden sollten, wenn sie können, und zu rohem 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-Tabellensyntax können Autoren führende und abschließende Pipes für Zeilen weglassen. Aus Gründen der Lesbarkeit müssen MDN-Autoren diese Pipes jedoch einfügen. Darüber hinaus müssen Autoren für die 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

Glücklicherweise wird die Tabellenformatierung von Prettier automatisch korrigiert, sodass sich Autoren auf Prettier verlassen können, um ihre Tabellen korrekt 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 im Klartext lesbar zu sein.
3. Der Autor möchte eine spezielle Art von Tabelle verwenden, die als "Eigenschaftentabelle" 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 Header-Spalte haben.
• GFM wird GFM-Blockelemente in Tabellenzellen nicht parsen. Zum Beispiel können Sie keine Liste in einer Tabellenzelle haben.
• GFM-Tabellen können keine Klassen zugewiesen werden.
• GFM unterstützt keine Tabellenelemente über <table>, <tr>, <th> und <td> hinaus.
• GFM unterstützt keine Tabellenattributen 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 in Tabellen nicht empfehlen, da dies auch die GFM-Syntax ausschließt.

Maximale Breite der GFM-Tabelle

Selbst wenn eine Tabelle in GFM geschrieben werden könnte, sollte manchmal besser HTML verwenden, weil GFM einen "ASCII Art" 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 wird dies so aussehen:

| 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 uns zum folgenden Leitfaden: 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 verwendet wird, um strukturierte Eigenschaft-Wert-Inhalte über eine Reihe von Seiten eines bestimmten Typs anzuzeigen. Diese Tabellen haben zwei Spalten: Die erste Spalte ist die Kopfzeilenspalte und listet die Eigenschaften auf, und die zweite Spalte listet ihre Werte für diesen bestimmten Artikel auf. Zum Beispiel, hier ist die Eigenschaftstabelle für die PannerNode Schnittstelle:

Diese Seiten können nicht in GFM dargestellt werden, da sie eine Kopfzeilenspalte haben, also 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 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 gelöst.

Autoren können die HTML-<sup> und <sub>-Elemente verwenden, wenn nötig, sollten aber Alternativen verwenden, wenn möglich. Insbesondere:

• Für Exponentiation verwenden Sie das Caret: 2^53.
• Für ordinale Ausdrücke wie 1^st bevorzugen Sie Worte wie "erstens".
• Für Fußnoten markieren Sie die Fußnotenzeichen nicht, z. B. <sup>[1]</sup>.

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

Die Seitenzusammenfassung ist der erste "Inhalts"-Absatz auf einer Seite—der erste Text, der nach der Seiten-Front-Matter und eventuellen Sidebar oder Seitenbanner Makros erscheint.

Diese Zusammenfassung wird für die Suchmaschinenoptimierung (SEO) verwendet und auch automatisch neben Seitenlisten von einigen Makros aufgenommen. Der erste Absatz sollte daher sowohl prägnant als auch informativ sein.

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

Autoren können KumaScript-Makroaufrufe in Prosa-Inhalte einfügen:

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")}}.

{{EmbedInteractiveExample("pages/css/margin.html")}}

The top and bottom margins have no effect on replaced inline elements, such as
{{HTMLElement("span")}} or {{HTMLElement("code")}}.

Siehe Makros verwenden für weitere Informationen zu Makros.