Guide relatif aux classes et styles utilisés dans le contenu de MDN

MDN dispose de nombreux styles prédéfinis qui peuvent être utilisés dans les articles. Cette page recense les différentes classes disponibles et comment les utiliser.

On gardera à l'esprit que ces styles ont été développés afin d'aborder la plupart des situations pour la mise en forme du contenu d'un article. Autant que possible, on devra utiliser ces classes disponibles pour éviter de créer une hétérogénéité de styles. Si vous pensez qu'une page nécessite une mise en forme spécifique, commencez par en discuter.

Styles en incise (inline)

Cette section référence les différents styles en incise qui sont disponibles pour les blocs de contenu sur MDN.

.button

Met en forme comme un bouton. Généralement utilisé pour mettre en forme des liens (les éléments <button> sont supprimés des sources des articles pour des raisons de sécurité).

Télécharger le code source

Exemple de syntaxe

<a href="https://github.com/mdn/simple-web-worker/archive/gh-pages.zip" class="button">Télécharger le code source</a>

.hidden

Permet de masquer le contenu dans la vue affichée au lecteur. Elle est généralement utilisée afin de fournir des blocs de code HTML, CSS et JavaScript complémentaires pour les exemples interactifs pour n'afficher que le contenu pertinent pour la page courante.

Exemple de syntaxe

<h4 id="Hidden_Code_Sample">Exemple de code masqué</h4>

<div class="hidden">
<h5 id="HTML">HTML</h5>

<pre class="brush: html;">
&lt;button id="test"&gt; Cliquez ici&lt;/button&gt;

<h5 id="CSS">CSS</h5>

<pre class="brush: css;">
button {
  background-color: #a00;
  color:#fff;
  font-size: 20px;
}
</pre>
</div>

<h5 id="JavaScript_Content">JavaScript</h5>

<pre class="brush: js;">
document.getElementById("test").addEventListener("click", works);
function works() {
  console.log("vous avez cliqué !");
}
</pre>

<p>{{EmbedLiveSample("Hidden_Code_Sample")}}</p>

Exemple de code masqué

JavaScript
document.getElementById("test").addEventListener("click", works);
function works(){
  console.log("vous avez cliqué !");
}

.seoSummary

Il s'agit d'une classe sans effet visible sur le contenu de la page. Toutefois, si la classe est appliquée à un élément (généralement un <span>), KumaScript utilisera le contenu de l'élément afin de créer une description via une balise <meta>. Celle-ci sera utilisée pour fournir une courte description dans les moteurs de recherche et sur les tuiles générées dans les messages sur les réseaux sociaux comme Facebook et Twitter.

Note

Si .seoSummary n'est pas explicitement utilisée sur une page, le premier paragraphe sera automatiquement utilisé comme telle description.

Exemple de syntaxe

<span class="seoSummary">
  Les extensions permettent aux développeuses et développeurs d'étendre les fonctionnalités d'un navigateur.
</span>

Exemple de <meta> généré

<meta name="description"
    content="Les extensions permettent aux développeuses et développeurs d'étendre les fonctionnalités d'un navigateur.">

Styles pour les éléments de bloc

Cette section énumère les différents styles permettant de mettre en forme les éléments de bloc sur MDN.

Coloration syntaxique du code

Pour créer un exemple de bloc de code sur MDN, on utilisera un élément <pre> :

<pre>p {
  color: red;
  /* Voici mon exemple de code */
}</pre>
Cela fournira le résultat suivant :
p {
  color: red;
  /* Voici mon exemple de code */
}

Si vous souhaitez indiquer une coloration syntaxique dans l'exemple de code, il faudra inclure un attribut class avec une valeur brush: type-de-langagetype-de-langage pourra être une valeur parmi :

  • bash
  • cpp (pour C/C++)
  • css
  • html
  • java
  • js (pour JavaScript)
  • json
  • php
  • python
  • sql
  • xml
  • wasm (pour le format texte WebAssembly)

Par exemple, pour utiliser une coloration syntaxique pour CSS, on pourra écrire :

<pre class="brush: css">p {
  color: red;
  /* Voici mon exemple de code */
}</pre>
Ce qui fournira le résultat suivant :
p {
  color: red;
  /* Voici mon exemple de code */
}

Si aucun langage pertinent n'est disponible, on pourra n'utiliser aucune valeur ou brush: plain afin d'avoir du code sans coloration syntaxique.

details

Un élément <details> peut être utilisé autour d'un bloc de contenu afin de masquer ce contenu et d'afficher un lien "▶︎ Détails" qui, lorsqu'on cliquera dessus, dévoilera son contenu.

Exemple de syntaxe

Voici un exemple de syntaxe pour l'élément <details> qui a été masqué avec <details>.

<details>
  <summary>
<h4>Exemple de syntaxe</h4>
  </summary>
<p>Voici un exemple de syntaxe pour l'élément <code>.detail</code> qui a été masqué avec <code>.detail</code>.</p>
</details>

Note

On peut inclure un attribut open sur l'élément <details> afin que celui-ci soit ouvert par défaut.

.example-bad et .example-good

Les exemples de bonnes et de mauvaises pratiques peuvent être signalés respectivement par les classes .example-good et .example-bad. Elles sont généralement utilisées pour les blocs <pre> indiquant des fragments de code à éviter. On peut cependant les utiliser sur d'autres blocs.

Exemple de code correct
<label for="test">Libellé de formulaire:</label>
<input type="text" id="test">
Exemple de code incorrect
<input type="text">

Il est nécessaire d'utiliser des titres pour ces classes (voir ci-après). En effet, CSS ne permet pas d'ajouter le message localisé qui indique si l'exemple est correct ou incorrect et qui permet de comprendre pour les personnes utilisant un lecteur d'écran ou celles pour qui rouge et vert ne signifient pas nécessairement mauvais/bon.

Exemple de syntaxe

<h5 id="Good_code_example">Exemple de code correct</h5>

<pre class="brush: html example-good">
  &lt;label for="test"&gt;Libellé de formulaire:&lt;/label&gt;
  &lt;input type="text" id="test"&gt;
</pre>

<h5 id="Bad_code_example">Exemple de code incorrect</h5>

<pre class="brush: html example-bad">
  &lt;input type="text"&gt;
</pre>

.note.notecard

Affiche le contenu d'une section dans une boîte signalant une note. Cette classe s'avère utile lorsqu'on souhaite indiquer quelque chose de relatif au contenu principal sans que cette information s'intègre directement dans le flux de l'article.

Note

Voici comment une note est généralement affichée sur MDN.

Nous avons ici utilisé un titre <h4> pour cet exemple mais il conviendra de choisir le niveau de titre qui correspond à la hiérarchie des titres du document courant.

Exemple de syntaxe

<div class="notecard note">
  <h4>Note</h4>
  <p>Voici comment une note est généralement affichée sur MDN.</p>
</div>

.notecard.warning

Affiche le contenu d'une section dans une boîte signalant un avertissement. Cela permet d'indiquer une information à laquelle la lectrice ou le lecteur doit faire particulièrement attention (par exemple lorsqu'il est nécessaire de faire quelque chose ou d'éviter quelque chose).

Attention !

La balise <blink> est obsolète !

Nous avons ici utilisé un titre <h4> pour cet exemple mais il conviendra de choisir le niveau de titre qui correspond à la hiérarchie des titres du document courant.

Exemple de syntaxe

<div class="notecard warning">
  <h4>Attention !</h4>
  <p>La balise &lt;blink&gt; est obsolète !</p>
</div>

Styles pour les tableaux

MDN fournit quelques styles pour la mise en forme des éléments <table>.

Sans classe ajoutée :

Thés préférés, décembre 2015
Variété Caféine Durée d'infusion Température de l'eau
Noir Élevée 2-3 minutes 99°C
Vert Faible à moyen 1-2 minutes 75 à 80°C
Caféine free
Tisane Aucune 3-6 minutes 99°C

.standard-table

Thés préférés, décembre 2015
Variété Caféine Durée d'infusion Température de l'eau
Noir Élevée 2-3 minutes 99°C
Vert Faible à moyen 1-2 minutes 75 à 80°C
Caféine free
Tisane Aucune 3-6 minutes 99°C

Notes

  • On notera les différents styles appliqués aux en-têtes (<th>) et les attributs scope utilisés pour l'accessibilité.

Exemple de syntaxe

<table class="standard-table">
 <caption>Thés préférés, décembre 2015</caption>
 <thead>
  <tr>
   <th scope="row">Variété</th>
   <th scope="col">Caféine</th>
   <th scope="col">Durée d'infusion</th>
   <th scope="col">Température de l'eau</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <th scope="row">Noir</th>
   <td>Élevée</td>
   <td>2-3 minutes</td>
   <td>99&nbsp;°C</td>
  </tr>
  <tr>
   <th scope="row">Vert</th>
   <td>Faible à moyen</td>
   <td>1-2 minutes</td>
   <td>75 à 80&nbsp;°C</td>
  </tr>
  <tr>
   <th scope="row">Infusion</th>
   <td>Aucune</td>
   <td>3-6 minutes</td>
   <td>99&nbsp;°C</td>
  </tr>
 </tbody>
</table>