Macros de liens

Listes de liens

MDN propose des macros qui créent une liste de liens :

{{SubpagesWithSummaries}} ^(angl.)

Insère une liste de définitions (<dl>) des sous-pages de la page courante, avec le titre de chaque page comme terme <dt> et son premier paragraphe comme terme <dd>.

{{ListSubpagesForSidebar()}} ^(angl.)

Sans paramètre, insère une liste ordonnée de liens vers les sous-pages de la page courante. Le premier paramètre est le slug de la page parente de l'arborescence. Le texte du lien est affiché comme code. Un second paramètre à true ou 1 convertit les liens en texte brut. Un troisième paramètre à true ou 1 ajoute un lien vers la page parente en haut de la liste avec « Aperçu » comme texte du lien.

{{QuickLinksWithSubpages()}} ^(angl.)

Crée un ensemble de liens rapides utilisant les enfants de la page courante (ou de la page définie) comme destinations. Cela crée des listes hiérarchiques jusqu'à deux niveaux. Les titres des pages sont utilisés comme texte du lien et leurs résumés comme info-bulle.

Par exemple, pour inclure une liste ordonnée de liens qui inclut cette page et ses pages sœurs, écrivez :

{{ListSubpagesForSidebar("/fr/docs/MDN/Writing_guidelines/Page_structures/Macros", 1)}}

Liens de renvoi croisé

Certaines macros créent un lien unique pour référencer une fonctionnalité CSS, JavaScript, SVG ou HTML, y compris des attributs, éléments, propriétés, types de données et API. Les macros qui créent des liens uniques nécessitent au moins un paramètre : la fonctionnalité référencée.

Ces macros sont :

• {{CSSxRef("")}} ^(angl.)
• {{DOMxRef("")}} ^(angl.)
• {{HTMLElement("")}} ^(angl.)
• {{Glossary("")}} ^(angl.)
• {{JSxRef("")}} ^(angl.)
• {{SVGAttr("")}} ^(angl.)
• {{SVGElement("")}} ^(angl.)
• {{HTTPMethod("")}} ^(angl.)
• {{HTTPStatus("")}} ^(angl.)

Utilisation simple

Pour le premier paramètre requis, vous dérivez le nom de la fonctionnalité à partir de la dernière section du slug du document vers lequel vous souhaitez créer un lien. Par exemple, pour créer un lien vers la page de l'élément <select> avec le slug Web/HTML/Reference/Elements/select, vous écrivez la macro comme {{HTMLElement("select")}}. Cela produit le lien « <select> », qui est à la fois formaté en code et inclut les chevrons. C'est parce que les macros ajoutent un formatage spécifique à la fonctionnalité au texte du lien. Ainsi, vous n'avez jamais à vous soucier de quoi que ce soit d'autre que le nom de la fonctionnalité elle-même lors de l'utilisation d'une macro. C'est pourquoi l'utilisation des macros pour ajouter des liens est rapide et facile.

Personnaliser le texte affiché

Par défaut, le texte affiché du lien est le premier paramètre passé à la macro. Pour afficher un texte différent, utilisez le deuxième paramètre. Par exemple, {{JSxRef("Array")}} produit Array. Pour afficher une variation de ce texte, utilisez {{JSxRef("Array", "Tableaux JavaScript")}}, ce qui produit Tableaux JavaScript. Vous pouvez remarquer que le lien résultant est formaté en code en raison du comportement par défaut de la macro. Consultez la section sur Désactiver le formatage du code pour voir comment ignorer le style de code.

Lien vers des pages imbriquées

Certaines fonctionnalités de référence ont des pages imbriquées pour des fonctionnalités connexes. Par exemple, l'élément HTML <input> a plusieurs pages imbriquées pour différents types d'entrée, comme Web/HTML/Reference/Elements/input/range pour le type d'entrée range.

En passant les informations de chemin à la macro dans le premier paramètre comme dans {{HTMLElement("input/range")}}, cela produit le lien « <input/range> », ce qui n'est pas ce que vous voulez. Utilisez le deuxième paramètre pour afficher un texte de lien différent. Ainsi, pour un lien vers le type d'entrée range, nous écririons la macro comme {{HTMLElement("input/range", "<code>&lt;input type=&quot;range&quot;&gt;</code>")}} pour produire « <input type="range"> ». (Notez que si le deuxième paramètre inclut un espace, comme celui entre input et type ici, cette macro supprime le formatage du code ; nous avons donc ajouté les balises <code> explicitement.)

Utiliser CSSxRef avec la référence CSS

Chaque macro est légèrement différente.

La macro CSSxRef détermine automatiquement le chemin correct à partir du nom de la fonctionnalité que vous fournissez en tant que premier paramètre à la macro. La macro détecte si une fonctionnalité est une propriété, un sélecteur, une règle @, une fonction ou un type de données, et crée un lien vers le document approprié sous Web/CSS/Reference/.

Par exemple :

• {{CSSxRef("cursor")}} crée un lien vers la page de la propriété à Web/CSS/Reference/Properties/cursor.
• {{CSSxRef(":hover")}} crée un lien vers la page de la pseudo-classe à Web/CSS/Reference/Selectors/:hover.
• {{CSSxRef("@media")}} crée un lien vers la page de la règle @ à Web/CSS/Reference/At-rules/@media.
• {{CSSxRef("pow")}} crée un lien vers la page de la fonction à Web/CSS/Reference/Values/pow.
• {{CSSxRef("<color>")}} crée un lien vers la page du type de données à Web/CSS/Reference/Values/color_value.

Tout comme la macro HTMLElement, la macro CSSxRef ajoute le style approprié au texte du lien en fonction du type de fonctionnalité. Ainsi, {{CSSxRef("acos")}} ajoute des crochets angulaires au texte du lien résultant comme dans acos().

Quelques autres comportements de la macro CSSxRef méritent d'être notés :

• Les pages imbriquées sont gérées automatiquement. Par exemple :

  • {{CSSxRef("basic-shape/circle")}} crée un lien vers le document à Web/CSS/Reference/Values/basic-shape/circle avec le lien circle().
  • {{CSSxRef("animation-timeline/scroll")}} crée un lien vers le document à Web/CSS/Reference/Properties/animation-timeline/scroll avec le lien scroll().

• Certaines fonctionnalités CSS ont le même nom. En plus de leur emplacement dans le répertoire, leurs chemins contiennent des suffixes pour refléter leur type. Par exemple, la propriété position a le chemin Web/CSS/Reference/Properties/position, tandis que le type de données <position> a le chemin Web/CSS/Reference/Values/position_value.

  La macro CSSxRef gère automatiquement ces fonctionnalités ayant le même nom. Ainsi, {{CSSxRef("position")}} crée un lien vers la page de la propriété avec le lien position, et {{CSSxRef("<position>")}} crée un lien vers la page du type de données avec le lien <position>.

  D'autres fonctionnalités ayant des noms partagés incluent :

  • La propriété color (Web/CSS/Reference/Properties/color) et le type de données <color> (Web/CSS/Reference/Values/color_value)

    Macro : {{CSSxRef("color")}} et {{CSSxRef("<color>")}}

  • La fonction fit-content() (Web/CSS/Reference/Values/fit-content_function) et le mot-clé fit-content (Web/CSS/Reference/Values/fit-content)

    Macro : {{CSSxRef("fit-content_function", "fit-content()")}} et {{CSSxRef("fit-content")}} (c'est actuellement une exception où vous devez fournir le deuxième paramètre pour obtenir le texte de lien correct pour la fonction.)

  • La propriété flex (Web/CSS/Reference/Properties/flex) et le type de données <flex> (Web/CSS/Reference/Values/flex_value)

    Macro : {{CSSxRef("flex")}} et {{CSSxRef("<flex>")}}

  • La pseudo-classe :host (Web/CSS/Reference/Selectors/:host) et la fonction pseudo-classe :host() (Web/CSS/Reference/Values/:host_function)

    Macro : {{CSSxRef(":host")}} et {{CSSxRef(":host()")}}

  • La propriété overflow (Web/CSS/Reference/Properties/overflow) et le type de données <overflow> (Web/CSS/Reference/Values/overflow_value)

    Macro : {{CSSxRef("overflow")}} et {{CSSxRef("<overflow>")}}

  • La fonction url() (Web/CSS/Reference/Values/url_function) et le type de données <url> (Web/CSS/Reference/Values/url_value)

    Macro : {{CSSxRef("url()")}} et {{CSSxRef("<url>")}}

Désactiver le formatage du code

Les macros de référence croisée appliquent par défaut un formatage de code au texte du lien. Pour éviter les styles de code HTML et CSS appliqués par les macros, utilisez le paramètre "nocode".

Par exemple, {{CSSxRef("background-color")}} crée le lien "background-color" avec le style de code, tandis que {{DOMxRef("CSS.supports_static", "check support", "", "nocode")}} crée le lien en texte brut « check support ». De même, pour créer le lien vers le tableau JavaScript sans formatage de code, nous écririons {{JSxRef("Array", "JavaScript arrays", "", "nocode")}} pour produire « JavaScript arrays ».

Voir aussi

• Utiliser les macros
• Macros courantes, y compris les macros BCD ({{Compat}}) et les macros de spécification ({{Specifications}}).
• Guide des bannières et avis incluant les macros {{SeeCompatTable}}, {{Deprecated_Header}} et {{SecureContext_Header}}.