Skip to content

Latest commit

 

History

History
281 lines (220 loc) · 13.3 KB

index.md

File metadata and controls

281 lines (220 loc) · 13.3 KB
Raw
title slug translation_of original_slug
Macros usuelles
MDN/Writing_guidelines/Page_structures/Macros/Commonly_used_macros
MDN/Structures/Macros/Commonly-used_macros
MDN/Structures/Macros/Commonly-used_macros

{{MDNSidebar}}

Cette page énumère les différentes macros utilisées sur MDN. Pour plus d'informations sur leur utilisation, voir Utiliser les macros.

Voir la page Autres macros pour plus d'informations quant aux macros moins usitées ou uniquement utilisées dans certains contextes ou qui sont dépréciées.

Liens

MDN fournit plusieurs macros pour former des liens entre les pages de référence, le glossaire, etc.

Attention : Toutes les macros de lien devraient être remplacées dans le contenu en français par des liens écrit en Markdown. En effet, on souhaite réduire l'utilisation des macros « simples » qui peuvent être facilement remplacées par du HTML/Markdown.

Liens vers le glossaire

La macro Glossary crée un lien vers la page d'un terme du glossaire. Elle prend un argument obligatoire et un autre optionnel :

  1. Le nom du terme (par exemple "HTML") : \{{Glossary("HTML")}}
  2. Un paramètre optionnel indiquant le texte à afficher à la place du terme : \{{Glossary("CSS", "Cascading Style Sheets")}}

Attention : Pour remplacer cette macro, on écrira plutôt : [le texte à afficher](/fr/docs/Glossary/MonTerme).

Liens vers des pages de référence

D'autres macros permettent de créer des liens vers des pages des différentes références de MDN : JavaScript, CSS, éléments HTML, SVG, etc.

Elles utilisent généralement un premier paramètre indiquant le nom de l'élément vers lequel lier. La plupart utilisent un deuxième argument qui permet de modifier le texte affiché.

Macro Pointe vers une page située sous À remplacer par
CSSxRef La référence CSS (/Web/CSS/Reference) \{{CSSxRef("cursor")}} devra être remplacé par [`cursor`](/fr/docs/Web/CSS/cursor).
DOMxRef La référence du DOM (/Web/API) \{{DOMxRef("Document")}} devra être remplacé par [`Document`](/fr/docs/Web/API/Document). S'il y a un deuxième paramètre : \{{DOMxRef("document.getElementsByName()","getElementsByName()")}} devra être remplacé par [`getElementsByName()`](/fr/docs/Web/API/Document/getElementsByName).
HTMLElement Référence des éléments HTML (/Web/HTML/Element) \{{HTMLElement("select")}} devra être remplacé par [`<select>`](/fr/docs/Web/HTML/Element/select).
HTMLAttrxRef Attribut HTML universel si aucun nom d'élément n'est indiqué ou attribut d'un élément si le nom de ce dernier est fourni. \{{HTMLAttrxRef("lang")}} devra être remplacé par [`lang`](/fr/docs/Web/HTML/Global_attributes/lang). \{{HTMLAttrxRef("type","input")}} devra être remplacé par [`type`](/fr/docs/Web/HTML/Element/input#attr-type).
JSxRef Référence JavaScript (/Web/JavaScript/Reference). \{{JSxRef("Promise")}} devra être remplacé par [`Promise`](/fr/docs/Web/JavaScript/Reference/Global_Objects/Promise)
SVGAttr Référence des attributs SVG (/Web/SVG/Attribute). \{{SVGAttr("d")}} devra être remplacé par [`d`](/fr/docs/Web/SVG/Attribute/d)
SVGElement Référence des éléments SVG (/Web/SVG/Element). \{{SVGElement("view")}} devra être remplacé par [`<view>`](/fr/docs/Web/SVG/Element/view)
HTTPHeader Référence des en-têtes HTTP (/Web/HTTP/Headers). \{{HTTPHeader("ACCEPT")}} devra être remplacé par [`ACCEPT`](/fr/docs/Web/HTTP/Headers/ACCEPT)
HTTPMethod Référence des méthodes de requête HTTP (/Web/HTTP/Methods). \{{HTTPMethod("HEAD")}} devra être remplacé par [`HEAD`](/fr/docs/Web/HTTP/Methods/HEAD)
HTTPStatus Référence des codes de statut HTTP (/Web/HTTP/Status) \{{HTTPStatus("404")}} devra être remplacé par [`404`](/fr/docs/Web/HTTP/Status/404)
Event. Référence des évènements (/Web/Events)

Note : Cette macro n'est plus particulièrement utile, car les évènements sont désormais placés sous leur élément DOM associé. \{{DOMxRef("Document.wheel_event")}} devrait être remplacé par [`Document.wheel_event`](/fr/docs/Web/API/Document/wheel_event)

Navigation entre les pages de chapitre d'un guide

Previous, Next, et PreviousNext permettent d'afficher des contrôles de navigation pour des articles qui forment une série.

Pour les deux premières macros, le seul paramètre nécessaire est l'emplacement de l'article cible.

Pour la macro PreviousNext, le premier paramètre correspond à la cible de l'article précédent dans la série et le deuxième paramètre correspond à la cible du prochain article.

Exemples de code

Barres latérales de navigation

Pour chaque grand ensemble de pages, on a des macros qui aident à la navigation sous la forme d'une barre à gauche. Elles permettent généralement de remonter à la page racine de la référence/du guide/du tutoriel et placent l'article dans la catégorie correspondante au sein de cette barre.

  • CSSRef génère la barre latérale pour les pages de la référence CSS.
  • HTMLSidebar génère la barre latérale pour les pages de la référence HTML.
  • APIRef génère la barre latérale pour les pages des références des API web.

Mise en forme

Indicateurs en ligne pour les documentations d'API

optional_inline et ReadOnlyInline sont utilisées dans les documentations d'API pour décrire la liste des propriétés d'un objet ou les paramètres d'une fonction.

Syntaxe

\{{Optional_Inline}}

ou

\{{ReadOnlyInline}}.

Exemples

  • isCustomObject {{ReadOnlyInline}}
    • : Un booléen qui indique, s'il vaut true, que l'objet est spécifique.
  • parameterX {{Optional_Inline}}
    • : Bla bla bla…

Indicateurs de statut et de compatibilité

Indicateurs en ligne sans paramètre

Non-standard

non-standard_inline insère une marque sur la ligne, indiquant que l'API n'a pas été standardisée et n'est pas en voie de standardisation.

Syntaxe

\{{Non-standard_Inline}}

Exemples
  • Icône : {{Non-standard_Inline}}

Expérimental

experimental_inline insère une marque sur la ligne, indiquant que l'API n'est pas largement implémentée et peut évoluer.

Syntaxe

\{{Experimental_Inline}}

Exemples
  • Icône : {{Experimental_Inline}}

Dépréciation

deprecated_inline insère une marque sur la ligne, indiquant que l'API ne devrait pas être utilisée, car elle a officiellement été dépréciée ou supprimée.

Syntaxe

\{{Deprecated_Inline}}

Exemples
  • Icône : {{Deprecated_Inline}}

Indicateurs pour les pages ou les sections

Les macros qui suivent possèdent la même sémantique que les équivalents en ligne abordés avant. Ces macros doivent être placées directement après le préambule de la page. On peut aussi les utiliser pour marquer une section donnée d'une page.

  • non-standard_header. Exemple : \{{Non-standard_Header}} {{Non-standard_Header}}
  • SeeCompatTable devrait être utilisée sur les pages documentant des fonctionnalités expérimentales. Exemple : \{{SeeCompatTable}} {{SeeCompatTable}}
  • deprecated_header. Exemple : \{{Deprecated_Header}} {{Deprecated_Header}}
  • secureContext_header devrait être utilisée sur les pages principales des interfaces ou d'aperçu des API, mais pas sur les sous-pages décrivant les méthodes ou les propriétés. Exemple : \{{SecureContext_Header}} {{SecureContext_Header}}

Indiquer qu'une fonctionnalité est disponible pour les web workers

La macro AvailableInWorkers insère une note localisée qui indique qu'une fonctionnalité est disponible dans le contexte d'un web worker. L'argument notservice peut être utilisé afin d'indiquer qu'une fonctionnalité est disponible pour les web workers mais pas pour les service workers.

Syntaxe
\{{AvailableInWorkers}}
\{{AvailableInWorkers("notservice")}}
Exemples

{{AvailableInWorkers}} {{AvailableInWorkers("notservice")}}