Seitentypen

Es gibt eine Reihe von Seitentypen, die auf MDN wiederholt verwendet werden. Dieser Artikel beschreibt diese Seitentypen, ihren Zweck und gibt Beispiele für jeden sowie Vorlagen zur Verwendung beim Erstellen einer neuen Seite.

Auf MDN gibt es drei große Kategorien von Seitentypen, obwohl einige Seitentypen in mehr als eine Kategorie fallen.

  • Referenzseiten beschreiben die Details von etwas und sind gemäß der Struktur des beschriebenen Objekts organisiert.
  • Leitfaden-Seiten beschreiben, wie man etwas tut oder verwendet, und sind basierend auf den Zielen des Lesers organisiert.
  • Navigationsseiten existieren in erster Linie, um Links zu anderen Seiten bereitzustellen, normalerweise über verwandte Themen.

Erstellen einer neuen Seite

Das Hinzufügen eines neuen Dokuments ist relativ einfach, besonders wenn Sie mit dem Kopieren einer index.md-Datei aus einem ähnlichen Thema beginnen können. Es gibt ein paar Dinge, die Sie beachten sollten:

  • Dokumente werden in Markdown in einer index.md-Datei geschrieben.
  • Wenn Sie beispielsweise ein neues Dokument für einen HTTP-Header namens foo erstellen, erstellen Sie einen neuen Ordner unter files/en-us/web/http/reference/headers/foo und legen Sie die Markdown-Datei in diesem Ordner ab (files/en-us/web/http/reference/headers/foo/index.md).
  • Eine index.md-Datei eines Dokuments muss mit einem Front-Matter beginnen, das den title, slug und meistens den page-type definiert. Es könnte hilfreich sein, sich auf das Front-Matter einer ähnlichen Dokumentation in einer index.md zu beziehen.

Verwendung der Vorlagen

Wenn Sie eine neue Seite erstellen, können Sie durch Beziehen auf eine unserer Seitentemplates sicherstellen, dass Sie die richtige Seitenstruktur/Inhalte verwendet haben – siehe die Abschnitte unten. Sie können den genauen Quellcode jeder Vorlage finden (wenn Sie ihn kopieren möchten), indem Sie dem "Source on GitHub"-Link am Ende jeder Vorlage folgen. Diese Seitentemplates machen als veröffentlichte Seiten nicht viel Sinn, aber wenn Sie ihren Quellcode anzeigen, werden Sie sehen, dass sie viele hilfreiche Kommentare, Platzhalter und Hinweise enthalten, die detaillieren, wie die fehlenden Informationen ausgefüllt und Ihre Seite erstellt werden können.

Am Anfang jeder Vorlage finden Sie einen Abschnitt mit dem Titel Vor der Veröffentlichung entfernen – dieser enthält Informationen darüber, wie Sie den Seitentitel, den Slug, das Seitenleistenmenü und die Tags ausfüllen können (z. B. Informationen, die nicht im Körper des Artikels erscheinen). Sie müssen diesen Abschnitt löschen, nachdem Sie die Anweisungen befolgt haben, bevor die Seite als fertig betrachtet werden kann.

Alte Seitenlayouts

Manchmal stoßen Sie auf alte Referenzseiten, die deutlich anders aussehen als die hier vorgestellten Vorlagen. Beispielsweise hatten alte Schnittstellenseiten alle Details der Mitglieder einer Schnittstelle auf einer einzigen Seite, und es gab keine einzelnen Seiten für Methode/Eigenschaft/Konstruktor/Ereignis-Listener.

Wenn Sie auf ein altes Set von Seiten stoßen, wären wir froh, wenn Sie diese auf den neuen Stil aktualisieren würden! Wir schätzen jedoch, dass dies eine Menge Arbeit sein kann. Wenn die Informationen zu aktualisieren nicht allzu umfangreich sind und Sie etwas Zeit haben, versuchen Sie es ruhig, sie auf den neuen Stil zu aktualisieren.

Wenn die Arbeit bedeutender ist, sollten Sie einige Faktoren berücksichtigen, wenn Sie die Prioritäten des Projekts festlegen:

  • Wie veraltet sind die Informationen?
  • Wie niedrig ist die Qualität der Informationen?
  • Wie beliebt ist die Funktion? Wie sehr wird die Information gesucht?

Wenn Sie ein Team zusammenstellen möchten, um an einem Update zu arbeiten, oder wenn Sie einfach nur einige Inhalte melden oder diskutieren möchten, die ein Update benötigen, zögern Sie nicht, ein Inhaltsproblem zu melden oder uns um Hilfe zu bitten.

Der Front-Matter-Schlüssel für Seitentypen

Wir haben einen Front-Matter-Schlüssel page-type definiert, um den Typ der MDN-Seiten klar zu identifizieren. Die unten verlinkten Vorlagen geben an, welche page-type-Werte Sie für jeden Seitentyp festlegen sollen.

Die vollständige Liste der Seitentypen finden Sie unter The page-type front matter key.

Seitentemplates

Unten finden Sie Beispiele für die verschiedenen Seiten, die Sie auf MDN finden, sowie Templates, die verwendet werden können, um neue Inhalte basierend auf dem Typ der präsentierten Inhalte zu erstellen, einschließlich der folgenden Seiten:

Jeder Abschnitt enthält Links zu Beispielen für diese Seitentypen.

API-Übersichtsseite

Eine API-Übersichtsseite bietet einen Überblick darüber, was eine bestimmte API tut, sowie Links zur Dokumentation für jede der angebotenen Schnittstellen, globalen Funktionen usw. Sie verlinkt nicht direkt auf spezifische Methoden oder Eigenschaften innerhalb der Klassen der API, außer im Kontext des Übersichtstextes. Sie ist in erster Linie eine Navigationsseite, aber sie fungiert auch als eine übersichtliche Referenzseite für die API.

Es gibt Fälle, in denen mehrere APIs existieren, die unterscheidbar und in eigenen Spezifikationen definiert sind, aber eng verwandt sind und deshalb sinnvollerweise mit einer einzigen API-Landingpage abgedeckt werden. Zum Beispiel behandelt die Generic Sensor API allgemeine Sensoren betreffenden Angelegenheiten, aber spezifischere Angelegenheiten werden in anderen APIs wie Ambient Light Sensor, Motion Sensor usw. behandelt. In solchen Fällen sind viele der grundlegenden Konzepte gleich, daher ergibt es keinen Sinn, diese über mehrere Landingpages hinweg zu wiederholen. In einem solchen Fall wäre es in Bezug auf Wiederholung und Auffindbarkeit sinnvoller, sie alle unter einer einzigen "Web-Sensoren"-Landingpage abzudecken.

Beispiel

Vorlagen

API-Referenzseite

Hinweis: Auch bekannt als eine Schnittstellen-Startseite.

Eine API-Referenzseite listet alle Methoden, Eigenschaften, Ereignisse usw. auf, die Mitglieder einer bestimmten Schnittstelle oder Klasse sind. Sie bietet einen Überblick darüber, was die Klasse oder Schnittstelle tut oder wofür sie verwendet wird, und gibt Links zur Dokumentation für jedes dieser Mitglieder. Sie ist granularer als eine API-Übersichtsseite, die typischerweise zu mehreren API-Referenzseiten verlinkt.

Beispiel

Vorlagen

API-Referenzunterseite

Eine API-Referenzunterseite ist ein Kind einer API-Referenzseite. Sie dokumentiert ein einzelnes Schnittstellenmitglied im Detail.

Beispiele

Vorlagen

HTML-Elementreferenzseite

Eine HTML-Referenzseite listet alle Attribute auf, die auf einem HTML-Element verfügbar sind, erklärt den Zweck und die Verwendung des Elements und bietet Beispiele, Browser-Kompatibilitätsinformationen und andere wichtige Daten.

Beispiel

Vorlagen

HTML-Attributreferenzseite

Eine HTML-Attributseite listet alle Werte auf, die auf einem HTML-Attribut existieren, erklärt den Zweck und die Anwendungsfälle des Attributs und bietet Beispiele, Browser-Kompatibilitätsinformationen und andere wichtige Daten.

Hinweis: Elementspezifische Attribute (wie placeholder für <input>) erfordern keine separate Seite, wenn die Attribute ausreichend innerhalb der Referenzseite des übergeordneten Elements behandelt werden können (zum Beispiel sollte das placeholder-Attribut auf der Seite des <input>-Elements behandelt werden, nicht als eigene Seite).

Beispiel

Vorlagen

SVG-Elementreferenzseite

Eine SVG-Referenzseite listet alle Attribute auf, die auf einem SVG-Element verfügbar sind, erklärt den Zweck und die Verwendung des Elements und bietet Beispiele, Browser-Kompatibilitätsinformationen und andere wichtige Daten.

Beispiel

Vorlagen

CSS-Modul-Übersichtsseite

Jedes CSS-Modul repräsentiert eine CSS-Spezifikation, die Unterstützung für bestimmte Funktionen und Implementierungen in CSS bietet. Zum Beispiel repräsentiert das Modul CSS-Boxmodell die Spezifikation, die die Rand- und Abstands-Eigenschaften beschreibt, mit denen Sie Abstand in und um eine CSS-Box herum schaffen können.

Eine CSS-Modul-Übersichtsseite bietet einen Überblick über die Funktionen, die das Modul bietet und listet alle Eigenschaften, Datentypen, CSS-Funktionen usw. auf, die das Modul bietet. Wenn möglich, bietet die CSS-Modul-Übersichtsseite eine schnelle Demonstration dessen, was mit den Eigenschaften des Moduls erreicht werden kann, durch ein interaktives Beispiel. Die Modul-Übersichtsseite dient in erster Linie als Navigationsseite, fungiert aber auch als eine Übersichtliche Referenzseite für das Modul.

Einige verwandte Eigenschaften und Funktionen, die zu anderen Modulen gehören, jedoch eng mit der Funktionalität verbunden sind, die das Modul, das Sie dokumentieren, bietet, können ebenfalls in einem Verwandte Konzepte-Abschnitt behandelt werden. Zum Beispiel wird der Datentyp <easing-function> und die prefers-reduced-motion-Media-Abfrage nicht im CSS-Animationsmodul behandelt, aber da sie eng mit CSS-Animationen verwandt sind, ist es eine gute Idee, sie im Verwandte Konzepte-Abschnitt der CSS-Animationsmodul-Übersichtsseite hervorzuheben.

Beispiele

Vorlagen

CSS-Feature-Referenzseite

Eine CSS-Referenzseite listet alle verfügbaren Syntaxen für ein CSS-Feature wie ein Selektor oder eine Eigenschaft auf und erklärt den Zweck und die Verwendung des Features. Sie bietet auch Beispiele, Browser-Kompatibilitätsinformationen und andere wichtige Daten.

Beispiele

Vorlagen

HTTP-Header-Referenzseite

Eine HTTP-Header-Referenzseite listet alle verfügbaren Direktiven auf, die ein HTTP-Header enthalten kann, und erklärt den Zweck und die Verwendung des Headers. Außerdem bietet sie Beispiele, Browser-Kompatibilitätsinformationen und andere wichtige Erklärungen.

Beispiel

Vorlagen

ARIA-Referenzseite

Eine ARIA-Referenzseite beschreibt eine Rolle oder ein Attribut, die Möglichkeiten definieren, um Webinhalte und Webanwendungen für Menschen mit Behinderungen zugänglicher zu machen.

Beispiele

Vorlagen

Konzeptuelle Seite

Eine konzeptuelle Seite ist eine Leitfaden-Seite, die etwas erklärt oder lehrt. Im Allgemeinen, wenn eine Seite hauptsächlich Prosa enthält und nicht in einen anderen Seitentyp fällt, ist sie wahrscheinlich eine konzeptuelle Seite. Eine erweiterte Diskussion eines Themas könnte sich über mehrere konzeptuelle Seiten erstrecken und über Next und Previous Makros verlinkt sein.

Beispiele

Glossarseite

Eine Glossarseite enthält eine kurze Erklärung eines Begriffs, Themas oder Konzepts. Der erste Absatz sollte eine einfache, abgeschlossene Beschreibung des Begriffs sein, nicht mehr als ein paar Sätze. Dies kann von Links zu weiterführenden Informationen im Abschnitt Siehe auch gefolgt werden. Wenn die Seite länger als etwa eine Bildschirmseite wird, ist sie zu lang und sollte in eine konzeptuelle Seite umgewandelt werden. Siehe Anleitung für das Schreiben und Verweisen eines Glossareintrags für weitere Details.

Beispiele

Vorlagen

Übersichtsseite

Eine Übersichtsseite dient als eine Art Menü für ihre Unterseiten und ist daher in erster Linie eine Navigationsseite. Ein Übersichtsseitenlayout wird typischerweise für die Hauptseite eines Seitenbaums über ein bestimmtes Thema verwendet. Sie beginnt mit einer kurzen Zusammenfassung des Themas und präsentiert dann eine strukturierte Liste von Links zu ihren Unterseiten und optional zusätzliches Material, das dem Leser nützlich sein könnte.

Die Liste der Unterseiten kann automatisch mit der SubpagesWithSummaries Vorlage generiert werden. In komplexeren Fällen muss die Liste jedoch manuell erstellt (und gepflegt) werden.

Webentwicklung lernen Seiten

Der Abschnitt Webentwicklung lernen von MDN richtet sich speziell an Personen, die die grundlegenden Grundlagen der Webentwicklung lernen, und erfordert daher einen anderen Ansatz als der andere Inhalt von MDN. Weitere Richtlinien finden Sie unter Richtlinien für das Schreiben von Webentwicklungsinhalten.

Es gibt nur wenige Seitentypen innerhalb von Webentwicklung lernen:

Modulgruppen-Übersichtsseite, z.B. Kernlernmodule

Diese enthalten einen Einführungstext, einen Abschnitt, der die Voraussetzungen beschreibt, die Sie vor dem Beginn der Modulgruppe haben sollten, und eine Liste der Module, gefolgt von einer optionalen Liste von "Siehe auch"-Links.

Modul-Übersichtsseite, z.B. Strukturierung von Inhalten mit HTML

Diese enthalten einen Einführungstext, einen Abschnitt, der die Voraussetzungen beschreibt, die Sie haben sollten, bevor Sie das Modul angehen, und eine Liste der enthaltenen Tutorials, gefolgt von einer optionalen Liste von "Zusätzlichen Tutorials", die verwandte aber nicht Teil des zentralen Lernpfades sind, und einer optionalen Liste von "Siehe auch"-Links.

Tutorial-Seite, z.B. Grundlegende HTML-Syntax

Die Struktur eines Lern-Tutorials ist nicht strikt, aber es muss ein praktisches Lernerlebnis bieten (siehe Richtlinien für das Schreiben von Webentwicklungsinhalten > Ansatz), es muss eine Reihe von "Voraussetzungen" und "Lernergebnissen" am Anfang auflisten, und der Inhalt muss die angegebenen Lernergebnisse unterrichten.

Beispiele

Siehe auch