Richtlinien zum Schreiben von HTML-Codebeispielen

Die folgenden Richtlinien beschreiben, wie HTML-Beispielcode für die MDN Web Docs geschrieben werden soll.

Allgemeine Richtlinien für HTML-Codebeispiele

Format wählen

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 den MDN Web Docs verwenden wir Prettier als Code-Formatter, um den Code-Stil konsistent zu halten (und um themenfremde Diskussionen zu vermeiden). Sie können unsere Konfigurationsdatei einsehen, um sich über die aktuellen Regeln zu informieren und die Prettier-Dokumentation zu 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 anzeigen müssen. Ein Snippet ist normalerweise ausreichend, um ein Feature zu demonstrieren. Wenn Sie das EmbedLiveSample-Makro verwenden, fügen Sie einfach das HTML-Snippet ein; es wird beim Anzeigen automatisch in ein vollständiges HTML-Dokument eingefügt.

Doctype

Sie sollten den HTML5-Doctype verwenden. Er ist kurz, leicht zu merken und abwärtskompatibel.

html

<!doctype html>

Dokumentensprache

Setzen Sie die Dokumentensprache mit dem lang-Attribut an 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 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 nahezu alle Zeichenbedürfnisse unabhängig von der verwendeten Sprache im Dokument ab.

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 mindestens Folgendes in Ihrem Dokument enthalten, was später nach Bedarf angepasst 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, Anführungszeichen wegzulassen, da HTML5 dies erlaubt, aber Markup ist übersichtlicher 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.

Boolean-Attribute

Setzen Sie keine Werte für Boolean-Attribute (aber setzen Sie Werte für enumerierte Attribute); Sie können einfach den Attributnamen schreiben, um es zu setzen. Zum Beispiel können Sie schreiben:

html

<input required />

Dies ist vollkommen verständlich und funktioniert einwandfrei. Ist ein Boolean-HTML-Attribut vorhanden, ist der Wert wahr. Auch wenn das Hinzufügen eines Wertes funktionieren würde, ist es nicht notwendig und falsch:

html

<input required="required" />

Groß-/Kleinschreibung

Verwenden Sie Kleinbuchstaben für alle Elementnamen und Attributnamen/-werte, weil es übersichtlicher aussieht und Sie Markup schneller schreiben können. Zum Beispiel:

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 case). Verwenden Sie nicht camel case. Zum Beispiel:

html

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

html

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

Zeichenreferenzen

Verwenden Sie keine Zeichenreferenzen unnötig — verwenden Sie soweit möglich das Literalzeichen (Sie müssen immer noch Zeichen wie spitze Klammern und Anführungszeichen escapen).

Zum Beispiel könnten Sie einfach schreiben:

html

<p>© 2018 Me</p>

Anstatt:

html

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

HTML-Elemente

Es gibt einige Regeln für das Schreiben über HTML-Elemente auf MDN Web Docs. Die Einhaltung dieser Regeln sorgt für konsistente Beschreibungen von Elementen und ihren Komponenten und gewährleistet korrekte Verlinkungen zu detaillierter Dokumentation.

Elementnamen: Verwenden Sie das HTMLElement-Makro, das einen Link zur entsprechenden MDN Web Docs-Seite für dieses Element erstellt. Zum Beispiel erzeugt das Schreiben von {{HTMLElement("title")}} "<title>". Wenn Sie keinen Link erstellen möchten, setzen Sie den Namen in spitze Klammern und verwenden Sie den Stil "Inline Code" (z. B. <title>).
Attributnamen: Verwenden Sie den Stil "Inline Code", um Attributnamen in code font zu formatieren. Setzen Sie sie zusätzlich in fett, wenn das Attribut im Zusammenhang mit einer Erklärung erwähnt wird, was es bewirkt oder wenn es zum ersten Mal auf der Seite verwendet wird.
Attributwerte: Verwenden Sie den Stil "Inline Code", um <code> auf Attributwerte anzuwenden, und verwenden Sie keine Anführungszeichen um Zeichenfolgenwerte, es sei denn, sie sind durch die Syntax eines Codesamples erforderlich. Zum Beispiel: "Wenn das type-Attribut eines <input>-Elements auf email oder tel gesetzt ist ...".