Richtlinien zum Schreiben von HTML-Codebeispielen
Die folgenden Richtlinien beschreiben, wie HTML-Codebeispiele für MDN Web Docs geschrieben werden sollen.
Allgemeine Richtlinien für HTML-Codebeispiele
Format auswählen
Meinungen über die richtige Einrückung, Leerzeichen und Zeilenlängen waren schon immer umstritten. Diskussionen über diese Themen lenken vom Erstellen und Pflegen von Inhalten ab.
Auf MDN Web Docs verwenden wir Prettier als Code-Formatter, um den Code-Stil konsistent zu halten (und um Off-Topic-Diskussionen zu vermeiden). Sie können in unserer Konfigurationsdatei die aktuellen Regeln einsehen und die Prettier-Dokumentation lesen.
Prettier formatiert den gesamten Code und sorgt für einen einheitlichen Stil. 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 Codeausschnitt reicht in der Regel aus, um eine Funktion zu demonstrieren. Wenn Sie das EmbedLiveSample-Makro verwenden, fügen Sie einfach den HTML-Ausschnitt ein. Dieser wird automatisch in ein vollständiges HTML-Dokument eingefügt, wenn er angezeigt wird.
Doctype
Sie sollten den Doctype für HTML5 verwenden. Er ist kurz, leicht zu merken und abwärtskompatibel.
<!doctype html>
Sprache des Dokuments
Zeichensatz des Dokuments
Sie sollten auch den Zeichensatz Ihres Dokuments wie folgt definieren:
<meta charset="utf-8" />
Verwenden Sie UTF-8, es sei denn, Sie haben dafür einen sehr guten Grund. UTF-8 deckt nahezu alle Zeichenanforderungen ab, unabhängig davon, welche Sprache in Ihrem Dokument verwendet wird.
Viewport-Meta-Tag
Fügen Sie immer das Viewport-Meta-Tag in den <head>
Ihres HTML-Dokuments ein, um sicherzustellen, dass das Codebeispiel auf mobilen Geräten besser funktioniert. Sie sollten mindestens das Folgende in Ihr Dokument einfügen, welches später nach Bedarf angepasst werden kann:
<meta name="viewport" content="width=device-width" />
Weitere Einzelheiten finden Sie unter Using the viewport meta tag to control layout on mobile browsers.
Attribute
Sie sollten alle Attributwerte in doppelte Anführungszeichen setzen. Es ist verlockend, die Anführungszeichen wegzulassen, da HTML5 dies erlaubt, aber der Markup-Code ist ordentlicher und leichter zu lesen, wenn Sie diese einschließen. Zum Beispiel ist dies besser:
<img src="images/logo.jpg" alt="A circular globe icon" class="no-border" />
…als dies:
<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
Geben Sie keine Werte für Boolean-Attribute an (aber geben Sie Werte für enumerierte Attribute an); Sie können einfach den Namen des Attributs schreiben, um es zu setzen. Zum Beispiel:
<input required />
Dies ist vollkommen verständlich und funktioniert einwandfrei. Wenn ein Boolean-HTML-Attribut vorhanden ist, ist der Wert wahr. Das Einschließen eines Wertes funktioniert zwar, ist aber nicht notwendig und falsch:
<input required="required" />
Groß- und Kleinschreibung
Verwenden Sie Kleinbuchstaben für alle Element- und Attributnamen/Werte, da dies ordentlicher aussieht und Sie Markup schneller schreiben können. Zum Beispiel:
<p class="nice">This looks nice and neat</p>
<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 kein camel case. Zum Beispiel:
<p class="editorial-summary">Blah blah blah</p>
<p class="bigRedBox">Blah blah blah</p>
Zeichenreferenzen
Verwenden Sie Zeichenreferenzen nur dann, wenn es unbedingt notwendig ist — verwenden Sie sofern möglich das tatsächliche Zeichen (Sie müssen dennoch Zeichen wie spitze Klammern und Anführungszeichen escapen).
Zum Beispiel könnten Sie einfach schreiben:
<p>© 2018 Me</p>
Anstatt:
<p>© 2018 Me</p>
HTML-Elemente
Es gibt einige Regeln für das Schreiben über HTML-Elemente auf MDN Web Docs. Das Einhalten dieser Regeln sorgt für konsistente Beschreibungen von Elementen und deren Komponenten und stellt außerdem sicher, dass Verlinkungen zu detaillierter Dokumentation korrekt sind.
- Elementnamen: Verwenden Sie das
HTMLElement
-Makro, das einen Link zur MDN Web Docs-Seite für dieses Element erstellt. Zum Beispiel erzeugt{{HTMLElement("title")}}
"<title>
". Wenn Sie keinen Link erstellen möchten, umschließen Sie den Namen mit spitzen Klammern und verwenden Sie den "Inline Code"-Stil (z. B.<title>
). - Attributnamen: Verwenden Sie den "Inline Code"-Stil, um Attributnamen in
code font
darzustellen. Zusätzlich setzen Sie sie infettgedruckt
, wenn das Attribut in Verbindung mit einer Erklärung seiner Funktion erwähnt wird oder wenn es zum ersten Mal auf der Seite benutzt wird. - Attributwerte: Verwenden Sie den "Inline Code"-Stil, 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 dastype
-Attribut eines<input>
-Elements aufemail
odertel
gesetzt ist ...".