Macros usuelles

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 (en-US) 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)

Liens vers des rapports de bogue

La macro bug permet de créer un lien vers un bogue de bugzilla.mozilla.org avec la syntaxe {{Bug(123456)}}. Un tel appel devrait être remplacé par [bogue Mozilla 123456](https://bugzilla.mozilla.org/show_bug.cgi?id=123456).

La macro WebkitBug fournit un lien vers la base de bogues de WebKit. Un tel lien devrait être remplacé par [bogue WebKit 7890](https://bugs.webkit.org/show_bug.cgi?id=7890).

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.
  • HTMLRef 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 Lecture seule

Un booléen qui indique, s'il vaut true, que l'objet est spécifique.

parameterX Facultatif

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

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

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

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: Cette fonctionnalité n'est ni standard, ni en voie de standardisation. Ne l'utilisez pas pour des sites accessibles sur le Web : elle ne fonctionnera pas pour tout utilisateur. Il peut également y avoir d'importantes incompatibilités entre les implémentations et son comportement peut être modifié dans le futur.

  • SeeCompatTable devrait être utilisée sur les pages documentant des fonctionnalités expérimentales. Exemple : {{SeeCompatTable}}

    Experimental: Cette fonction est expérimentale
    Puisque cette fonction est toujours en développement dans certains navigateurs, veuillez consulter le tableau de compatibilité pour les préfixes à utiliser selon les navigateurs.
    Il convient de noter qu'une fonctionnalité expérimentale peut voir sa syntaxe ou son comportement modifié dans le futur en fonction des évolutions de la spécification.

  • deprecated_header. Exemple : {{Deprecated_Header}}

    Obsolète: Cette fonctionnalité a été supprimée des standards du Web. Bien que quelques navigateurs puissent encore la supporter, elle est en cours d'éradication. Ne l'utilisez ni dans d'anciens projets, ni dans de nouveaux. Les pages et applications Web l'utilisant peuvent cesser de fonctionner à tout moment.

  • 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}}

    Contexte sécurisé: Cette fonctionnalité est uniquement disponible dans des contextes sécurisés (HTTPS), pour certains navigateurs qui la prennent en charge.

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

Note: Cette fonctionnalité est disponible via les Web Workers

Note: This feature is available in Web Workers, except for Service Workers