Leitfaden für das Schreiben von HTML-Codebeispielen

Die folgenden Richtlinien decken ab, wie HTML-Beispielcode für MDN Web Docs geschrieben wird.

Allgemeine Richtlinien für HTML-Codebeispiele

Wahl eines Formats

Meinungen über die richtige Einrückung, Leerzeichen und Zeilenlängen waren schon immer umstritten. Diskussionen zu diesen Themen lenken von der Erstellung und Pflege von Inhalten ab.

Auf MDN Web Docs verwenden wir Prettier als Code-Formatter, um den Codelayout konsistent zu halten (und um themenfremde Diskussionen zu vermeiden). Sie können unsere Konfigurationsdatei einsehen, um mehr über die aktuellen Regeln zu erfahren, und die Prettier-Dokumentation lesen.

Prettier formatiert den gesamten Code und hält den Stil konsistent. Dennoch gibt es einige zusätzliche Regeln, die Sie befolgen müssen.

Vollständiges HTML-Dokument

Hinweis: Die Richtlinien in diesem Abschnitt gelten nur, wenn Sie ein vollständiges HTML-Dokument zeigen müssen. Ein Snippet reicht normalerweise aus, um ein Feature zu demonstrieren. Wenn Sie den EmbedLiveSample-Makro verwenden, fügen Sie einfach das HTML-Snippet ein; es wird automatisch in ein vollständiges HTML-Dokument eingefügt, wenn es angezeigt wird.

Doctype

Sie sollten den HTML5-Doctype verwenden.

html

<!doctype html>

Dokumentensprache

Setzen Sie die Dokumentensprache mit dem lang-Attribut in Ihrem <html>-Element:

html

<html lang="en-US"></html>

Dies ist gut für die Barrierefreiheit und Suchmaschinen, hilft bei der Lokalisierung von Inhalten und erinnert die Menschen daran, bewährte Praktiken zu verwenden.

Zeichensatz des Dokuments

Sie sollten auch den Zeichensatz Ihres Dokuments wie folgt definieren:

html

<meta charset="utf-8" />

Verwenden Sie UTF-8, es sei denn, Sie haben einen sehr guten Grund dies nicht zu tun; es deckt alle Zeichenanforderungen ab, unabhängig davon, welche Sprache Sie in Ihrem Dokument verwenden.

Viewport-Meta-Tag

Schließlich sollten Sie immer das Viewport-Meta-Tag in Ihrem HTML-<head> hinzufügen, um dem Codebeispiel eine bessere Chance zu geben, auf mobilen Geräten zu funktionieren. Sie sollten zumindest das Folgende in Ihr Dokument einfügen, das später bei Bedarf modifiziert werden kann:

html

<meta name="viewport" content="width=device-width" />

Siehe Verwendung des Viewport-Meta-Tags zur Steuerung des Layouts auf mobilen Browsern für weitere Details.

Attribute

Sie sollten alle Attributwerte in Anführungszeichen setzen. Es ist verlockend, die Anführungszeichen wegzulassen, da HTML5 dies erlaubt, aber das Markup ist ordentlicher und leichter zu lesen, wenn Sie sie einfügen. Zum Beispiel ist dies besser:

html

<img src="images/logo.jpg" alt="A circular globe icon" class="no-border" />

…als dies:

html

<img src=images/logo.jpg alt=A circular globe icon class=no-border>

Das Weglassen von Anführungszeichen kann auch Probleme verursachen. Im obigen Beispiel wird das alt-Attribut als mehrere Attribute interpretiert, da keine Anführungszeichen angeben, dass "A circular globe icon" ein einzelner Attributwert ist.

Boolesche Attribute

Geben Sie keine Werte für boolesche Attribute an (aber für auflistbare Attribute schon); Sie können einfach den Namen des Attributs schreiben, um es zu setzen. Zum Beispiel können Sie schreiben:

html

<input required />

Dies ist völlig verständlich und funktioniert einwandfrei. Wenn ein boolesches HTML-Attribut vorhanden ist, ist der Wert wahr. Während die Angabe eines Wertes funktionieren wird, ist es nicht notwendig und inkorrekt:

html

<input required="required" />

Schreibkonvention auf MDN

Verwenden Sie Kleinbuchstaben für alle insensitiven Konstrukte, einschließlich der Doctype-Deklaration, Elementnamen und Attributnamen/-werte. Dies schafft ein einheitliches Erscheinungsbild und ermöglicht schnelleres Schreiben von Markup.

html

<p class="nice">This looks nice and neat</p>

html

<P CLASS="WHOA-THERE">Why is my markup shouting?</P>

Klassen- und ID-Namen

Verwenden Sie semantische Klassen-/ID-Namen und trennen Sie mehrere Wörter mit Bindestrichen (Kebab-Schreibweise). Verwenden Sie nicht die Camel-Schreibweise. Zum Beispiel:

html

<p class="editorial-summary">Blah blah blah</p>

html

<p class="bigRedBox">Blah blah blah</p>

Zeichenreferenzen

Verwenden Sie Zeichenreferenzen nicht unnötig — verwenden Sie, wo immer möglich, das tatsächliche Zeichen (Sie müssen dennoch Zeichen wie Winkelklammern und Anführungszeichen escapen).

Als Beispiel könnten Sie einfach schreiben:

html

<p>© 2018 Me</p>

Anstelle von:

html

<p>&copy; 2018 Me</p>

HTML-Elemente

Es gibt einige Regeln für das Schreiben über HTML-Elemente auf MDN Web Docs. Das Einhalten dieser Regeln führt zu konsistenten Beschreibungen von Elementen und deren Komponenten und sorgt auch für die korrekte Verlinkung zu ausführlicher Dokumentation.

Elementnamen: Verwenden Sie den HTMLElement-Makro, der einen Link zur MDN Web Docs-Seite für dieses Element erstellt. Wenn Sie zum Beispiel {{HTMLElement("title")}} schreiben, ergibt das "<title>". Wenn Sie keinen Link erstellen möchten, schließen Sie den Namen in spitze Klammern ein und verwenden Sie den "Inline Code"-Stil (z.B. <title>).
Attributnamen: Verwenden Sie den "Inline Code"-Stil, um Attributnamen in code-Schriftart zu setzen. Zusätzlich setzen Sie sie in fetter Schrift, wenn das Attribut in Verbindung mit einer Erklärung dessen, was es tut, erwähnt wird oder wenn es auf der Seite zum ersten Mal verwendet wird.
Attributwerte: Verwenden Sie den "Inline Code"-Stil, um <code> auf Attributwerte anzuwenden, und setzen Sie keine Anführungszeichen um Zeichenfolgenwerte, es sei denn, dies wird von der Syntax eines Codebeispiels benötigt. Zum Beispiel: "Wenn das type-Attribut eines <input>-Elements auf email oder tel gesetzt ist ...".