Encadrés

Les encadrés — admonitions, alertes, appelez-les comme vous voulez — sont des blocs de citation dotés d’une couleur, d’une icône et d’une étiquette, qui signalent ce qu’un lecteur pressé ne doit pas manquer.

La décision importante ici a été de ne pas inventer une syntaxe. Ce site rend l’extension d’alertes de GitHub, celle-là même qu’utilise Bear. Une note rédigée dans Bear se colle dans un billet et s’affiche correctement, sans rien traduire. C’est tout l’intérêt: les notes et le site publié partagent un seul format.

Les cinq types standards#

> [!NOTE]
> Information utile à connaître, même en survolant le contenu.

> [!TIP]
> Conseil pratique pour faire les choses mieux ou plus simplement.

> [!IMPORTANT]
> Information clé pour atteindre son objectif.

> [!WARNING]
> Information urgente exigeant une attention immédiate.

> [!CAUTION]
> Avertit d’un risque ou d’une conséquence négative.

Ce qui donne:

La distinction qui compte vraiment à l’écriture est celle entre avertissement et attention. L’avertissement porte sur l’attention du lecteur: quelque chose ira mal si vous survolez ce passage. L’attention porte sur les conséquences d’une action: cette étape peut détruire des données. Si rien de fâcheux n’arrive quand on l’ignore, c’est une note.

Un bloc de citation ordinaire reste un bloc de citation. Utilisez-le pour citer. Utilisez pullquote seulement lorsqu’une citation doit devenir un temps fort éditorial dans la page, pas simplement une preuve citée.

Citations mises en exergue#

pullquote isole une courte phrase du texte environnant. Il convient à une phrase mémorable, à un fragment de dialogue représentatif ou à une ligne qui donne le rythme de l’article. Ce n’est pas un indicateur de gravité, et il ne remplace pas les encadrés.

{{< pullquote >}}
Une URL prévisible est une courtoisie. Un lien brisé est une promesse brisée.
{{< /pullquote >}}

Ce qui donne:

Titres personnalisés#

Le texte placé après le type remplace l’étiquette par défaut:

> [!IMPORTANT] L’enregistrement expire tous les trois ans
> Inscrivez le renouvellement à l’agenda.

Les titres sont localisés lorsqu’on ne les remplace pas: un [!TIP] devient Tip en anglais et Conseil en français, de sorte que le même fichier fonctionne dans les deux langues sans rien coder en dur.

Contenu riche#

Les encadrés acceptent du Markdown normal — listes, code en ligne, emphase, liens:

> [!NOTE]
> Trois choses à savoir:
>
> - Les listes fonctionnent
> - Le `code en ligne` aussi
> - Et l’**emphase**

Le sixième type: archive#

archive est propre à ce site, sans équivalent GitHub: il reste donc un shortcode. Il signale une page conservée pour mémoire plutôt que tenue à jour — la plupart des pages de versions de macOS en portent un.

{{< callout type="archive" >}}
Cette page documente une version qu’Apple ne prend plus en charge.
{{< /callout >}}

Ce qui donne:

Le shortcode accepte toujours tous les types, et danger est conservé comme alias de caution pour que les anciens billets continuent de fonctionner. Pour tout sauf archive, préférez la syntaxe Markdown: elle survit à une copie hors du site.

Comment ça fonctionne#

Un render hook de bloc de citation, dans layouts/_default/_markup/render-blockquote.html, inspecte chaque bloc et confie ceux qui portent un marqueur d’alerte à layouts/partials/callout.html. Le shortcode appelle ce même partiel: les deux points d’entrée ne peuvent donc pas diverger.

Les encadrés signalent une gravité. Ils ne servent délibérément pas à pointer vers d’autres pages — c’est un mécanisme distinct et plus discret, décrit dans renvois. Une note compagnon habillée en avertissement apprend au lecteur à ignorer les avertissements.

Accessibilité#

• Le type n’est jamais porté par la couleur seule : chaque encadré affiche une étiquette textuelle localisée et visible — Note, Conseil, Important, Avertissement, Attention, Note d’archive — rendue en texte réel avant le corps, et l’icône à côté est aria-hidden="true" et purement décorative
• Le conteneur est un simple <div>, pas role="alert" ni role="status" — un encadré est du contenu de page statique, pas une annonce en direct, et ne porte donc aucun rôle ARIA live ni n’interrompt quoi que ce soit
• Aucun élément à l’intérieur de l’encadré ne prend le focus ni ne gère les touches; les liens et le code à l’intérieur du corps gardent leur comportement natif
• Évitez un titre personnalisé qui retire le mot de gravité — un titre personnalisé doit encore se lire comme ce qu’il est (un avertissement, une note) plutôt que de ne correspondre qu’à la couleur environnante