1. MDN Web Docs
  2. Règles d'écriture
  3. Structures des documents
  4. Types de pages

Cette page a été traduite à partir de l'anglais par la communauté. Vous pouvez contribuer en rejoignant la communauté francophone sur MDN Web Docs.

View in English Always switch to English

Types de pages

Il existe plusieurs types de pages qui sont utilisés de façon répétée sur MDN. Cet article décrit ces types de pages, leur objectif, et donne des exemples pour chacun ainsi que des modèles à utiliser lors de la création d'une nouvelle page.

Il existe trois grandes catégories de types de pages sur MDN, bien que certains types puissent appartenir à plusieurs catégories.

  • Les pages de référence décrivent les détails d'un élément et sont organisées selon la structure de l'élément décrit.
  • Les pages de guide expliquent comment faire ou utiliser quelque chose, et sont organisées selon les objectifs du·de la lecteur·ice.
  • Les pages de navigation servent principalement à fournir des liens vers d'autres pages, généralement sur des sujets associés.

Création d'une nouvelle page

Ajouter un nouveau document est relativement simple, surtout si vous pouvez commencer par copier un fichier index.md d'un sujet similaire. Quelques points à garder à l'esprit :

  • Les documents sont rédigés en Markdown dans un fichier index.md.
  • Par exemple, si vous créez un nouveau document pour un en-tête HTTP appelé foo, créez un nouveau dossier à files/en-us/web/http/reference/headers/foo et placez le fichier Markdown dans ce dossier (files/en-us/web/http/reference/headers/foo/index.md).
  • Le fichier index.md d'un document doit commencer par un front-matter définissant le title, le slug et, la plupart du temps, le page-type. Il peut être utile de consulter le front-matter d'un fichier index.md similaire.

Utiliser les modèles

Lorsque vous créez une nouvelle page, vous pouvez vous assurer d'utiliser la bonne structure et le bon contenu en consultant l'un de nos modèles de page — voir les sections ci-dessous. Vous pouvez trouver le code source exact de chaque modèle (si vous souhaitez le copier) en suivant le lien « Source sur GitHub » en bas de chaque modèle. Ces modèles de page n'ont pas beaucoup de sens en tant que pages publiées, mais si vous consultez leur code source, vous verrez qu'ils contiennent de nombreux commentaires utiles, des espaces réservés et des conseils détaillant comment remplir les informations manquantes et créer votre page.

En haut de chaque modèle, vous trouverez une section intitulée À supprimer avant publication — elle contient des informations sur la façon de remplir le titre de la page, le slug, le menu latéral et les tags (par exemple, des informations qui n'apparaissent pas dans le corps de l'article). Vous devez supprimer cette section après avoir suivi les instructions, avant que la page ne soit considérée comme terminée.

Anciennes mises en page

Il arrive parfois de tomber sur d'anciennes pages de référence qui sont très différentes des modèles présentés ici. Par exemple, les anciennes pages d'interface regroupaient tous les membres d'une interface sur une seule page, et il n'existait pas de pages individuelles pour chaque méthode/propriété/constructeur/écouteur d'événement.

Si vous tombez sur un ensemble de pages au format ancien, nous serions ravi·e·s que vous les mettiez à jour au nouveau format ! Cependant, nous comprenons que cela puisse représenter beaucoup de travail. Si la quantité d'informations à mettre à jour n'est pas trop importante et que vous avez un peu de temps, n'hésitez pas à essayer de les mettre à jour au nouveau format.

Si le travail est plus conséquent, vous devez prendre en compte quelques facteurs pour prioriser la mise à jour :

  • À quel point l'information est-elle obsolète ?
  • Quelle est la qualité de l'information ?
  • La fonctionnalité est-elle populaire ? L'information est-elle recherchée ?

Si vous souhaitez constituer une équipe pour travailler sur une mise à jour, ou simplement signaler ou discuter d'un contenu à mettre à jour, n'hésitez pas à ouvrir un ticket de contenu (angl.) ou à nous demander de l'aide.

Clé front-matter « page-type »

Nous avons défini une clé front-matter page-type pour identifier clairement le type de page MDN. Les modèles ci-dessous indiquent quelle valeur de page-type utiliser pour chaque type de page.

Pour la liste complète des types de pages, voir La clé front-matter page-type.

Modèles de page

Vous trouverez ci-dessous des exemples des différents types de pages présents sur MDN, ainsi que des modèles à utiliser pour créer de nouveaux contenus selon le type de contenu à présenter, notamment :

Chaque section inclut des liens vers des exemples de pages réelles pour chaque type.

Page d'accueil d'API

Une page d'accueil d'API (API) donne un aperçu de ce que fait une API particulière, ainsi que des liens vers la documentation de chaque interface, global, fonction, etc. proposés par l'API. Elle ne lie pas directement vers des méthodes ou propriétés spécifiques des classes de l'API, sauf dans le texte d'introduction. Il s'agit principalement d'une page de navigation, mais elle sert aussi de page de référence synthétique pour l'API.

Il existe des cas où plusieurs API distinctes sont définies dans leurs propres spécifications, mais sont étroitement liées et il est donc pertinent de les regrouper sur une seule page d'accueil d'API. Par exemple, la Generic Sensor API couvre les aspects généraux des capteurs, mais des aspects plus spécifiques sont couverts dans d'autres API comme Ambient Light Sensor, Motion Sensor, etc. Dans ces cas, de nombreux concepts de haut niveau sont identiques, il n'est donc pas pertinent de les répéter sur plusieurs pages d'accueil. Il est alors préférable, pour éviter la répétition et améliorer la recherche, de tout regrouper sous une seule page d'accueil « Web sensors ».

Exemple

Modèle

Page de référence d'API

Note : Aussi appelée page d'accueil d'interface.

Une page de référence d'API liste toutes les méthodes, propriétés, événements, etc. qui sont membres d'une interface ou classe donnée. Elle donne un aperçu de ce que fait la classe ou l'interface, ou de son usage, et fournit des liens vers la documentation de chacun de ses membres. Elle est plus détaillée qu'une page d'accueil d'API, qui lie généralement vers plusieurs pages de référence d'API.

Exemple

Templates

Sous-page de référence d'API

Une sous-page de référence d'API est une page enfant d'une page de référence d'API. Elle documente en détail un seul membre d'interface.

Exemples

Modèles

Page de référence d'élément HTML

Une page de référence HTML liste tous les attributs disponibles sur un élément HTML, explique l'objectif et l'utilisation de l'élément, et fournit des exemples, des informations sur la compatibilité des navigateurs et d'autres données importantes.

Exemple

Modèles

Page de référence d'attribut HTML

Une page de référence d'attribut HTML liste toutes les valeurs existantes pour un attribut HTML, explique l'objectif et les cas d'utilisation de l'attribut, et fournit des exemples, des informations sur la compatibilité des navigateurs et d'autres données importantes.

Note : Les attributs spécifiques à un élément (par exemple, placeholder pour <input>) ne nécessitent pas de page séparée si l'attribut peut être suffisamment couvert dans la page de référence de l'élément parent (par exemple, l'attribut placeholder doit être documenté sur la page de l'élément <input>, et non comme une page indépendante).

Exemple

Modèles

Page de référence d'élément SVG

Une page de référence SVG liste tous les attributs disponibles sur un élément SVG, explique l'objectif et l'utilisation de l'élément, et fournit des exemples, des informations sur la compatibilité des navigateurs et d'autres données importantes.

Exemple

Modèles

Page d'accueil de module CSS

Chaque module CSS représente une spécification CSS qui fournit la prise en charge de certaines fonctionnalités et implémentations en CSS. Par exemple, le module Modèle de boîte CSS représente la spécification qui décrit les propriétés de marge et de remplissage permettant de créer des espacements dans et autour d'une boîte CSS.

Une page d'accueil de module CSS donne un aperçu des fonctionnalités offertes par le module et liste toutes les propriétés, types de données, fonctions CSS, etc. proposés par le module. Lorsque c'est possible, la page d'accueil du module CSS propose une démonstration rapide de ce qu'il est possible de réaliser avec les propriétés du module via un exemple interactif. La page d'accueil du module sert principalement de page de navigation, mais fait aussi office de page de référence synthétique pour le module.

Certaines propriétés et fonctionnalités associées qui appartiennent à d'autres modules, mais qui sont étroitement liées à la fonctionnalité offerte par le module que vous documentez, peuvent aussi être abordées dans une section Concepts associés. Par exemple, le type de données <easing-function> et la media query prefers-reduced-motion ne sont pas couverts dans le module CSS animations, mais comme ils sont étroitement liés aux animations CSS, il est pertinent de les mettre en avant dans la section Concepts associés de la page d'accueil du module CSS animations.

Exemples

Modèles

Page de référence de fonctionnalité CSS

Une page de référence CSS liste toutes les syntaxes disponibles pour une fonctionnalité CSS telle qu'un sélecteur ou une propriété, et explique l'objectif et l'utilisation de la fonctionnalité. Elle fournit aussi des exemples, des informations sur la compatibilité des navigateurs et d'autres données importantes.

Exemples

Modèles

Page de référence d'en-tête HTTP

Une page de référence d'en-tête HTTP liste toutes les directives disponibles qu'un en-tête HTTP peut contenir, et explique l'objectif et l'utilisation de l'en-tête. Elle fournit aussi des exemples, des informations sur la compatibilité des navigateurs et d'autres explications importantes.

Exemple

Modèles

Page de référence ARIA

Une page de référence ARIA décrit un rôle ou un attribut qui définit des moyens de rendre le contenu web et les applications web plus accessibles aux personnes en situation de handicap.

Exemples

Modèles

Page conceptuelle

Une page conceptuelle est une page de guide qui explique ou enseigne quelque chose. En général, si une page contient principalement du texte explicatif et ne correspond à aucun autre type de page, il s'agit probablement d'une page conceptuelle. Une discussion approfondie sur un sujet peut être répartie sur plusieurs pages conceptuelles, reliées entre elles à l'aide des macros Next et Previous.

Exemples

Page de glossaire

Une page de glossaire contient une brève explication d'un terme, d'un sujet ou d'un concept. Le premier paragraphe doit être une description simple et autonome du terme, ne dépassant pas quelques phrases. Cela peut être suivi de liens vers des informations complémentaires dans la section Voir aussi. Si la page devient trop longue (plus d'un écran environ), elle doit être convertie en page conceptuelle. Voir Comment écrire et référencer une entrée du glossaire pour plus de détails.

Exemples

Modèles

Page d'accueil

Une page d'accueil sert de menu pour ses sous-pages, et est donc principalement une page de navigation. La structure d'une page d'accueil est généralement utilisée pour la page racine d'un ensemble de pages sur un sujet particulier. Elle commence par un bref résumé du sujet, puis présente une liste structurée de liens vers ses sous-pages, et éventuellement, du contenu supplémentaire utile au·à la lecteur·ice.

La liste des sous-pages peut être générée automatiquement à l'aide du modèle SubpagesWithSummaries (angl.). Cependant, dans les cas plus complexes, la liste peut devoir être créée (et maintenue) manuellement.

Pages « Apprendre le développement web »

La section Apprendre le développement web de MDN s'adresse spécifiquement aux personnes qui apprennent les bases du développement web, et nécessite donc une approche différente du reste du contenu MDN. Vous trouverez plus de conseils dans Règles de rédaction pour Apprendre le développement web.

Il n'existe que quelques types de pages dans « Apprendre le développement web » :

Page d'accueil de groupe de modules, par exemple Modules d'apprentissage de base

Ces pages contiennent un paragraphe d'introduction, une section détaillant les prérequis à avoir avant de commencer le groupe de modules, et une liste des modules, suivie d'une liste optionnelle de liens « Voir aussi ».

Page d'accueil de module, par exemple Structurer le contenu avec HTML

Ces pages contiennent un paragraphe d'introduction, une section détaillant les prérequis à avoir avant de commencer le module, et une liste des tutoriels inclus, suivie d'une liste optionnelle de « Tutoriels supplémentaires » qui sont liés mais ne font pas partie du parcours d'apprentissage principal, et d'une liste optionnelle de liens « Voir aussi ».

Page de tutoriel, par exemple Syntaxe HTML de base

La structure d'un tutoriel « Apprendre » n'est pas stricte, mais il doit proposer une expérience d'apprentissage pratique (voir Règles de rédaction pour Apprendre le développement web > Approche), il doit comporter une section « Pré-requis » et « Objectifs d'apprentissage » en haut de page, et le contenu doit enseigner les objectifs d'apprentissage annoncés.

Exemples

Voir aussi

Help improve MDN

Learn how to contribute

Cette page a été modifiée le par les contributeurs du MDN.

View this page on GitHub • Report a problem with this content