Intégration des composants DSFR

Contexte

Le système de design de l'Etat (DSFR) intègre des composants d'interface évolués. Tout ce qui peut être intégré par la syntaxe Markdown ou la mise en page de base Mkdocs est transformé en composant compatible avec le DSFR : blocs de citation, tableaux, menu latéral, en-têtes et pieds de pages, etc.

Cependant, la syntaxe standard du format Markdown ne permet pas d'intégrer tous les composants du DSFR. Par exemple, les badges, les tuiles, ou encore le système de grille permettant de définir deux colonnes de présentation sont autant de composants non pris en charge par le format Markdown.

Pour ces composants, mkdocs-dsfr s'inspire des bonnes pratiques d'autres thèmes, comme mkdocs-material, et propose une syntaxe d'intégration de composants DSFR. Cette syntaxe est inspirée de la syntaxe Markdown, mais elle est plus riche et permet d'intégrer des composants plus complexes.

Format général d'un composant DSFR

Le format général d'un composant DSFR est le suivant :

/// <nom du composant> | <titre éventuel>
    <paramètre 1>: <valeur 1>
    <paramètre 2>: <valeur 2>
    ...
    <paramètre n>: <valeur n>
Contenu inclus dans le composant. La notation Markdown est **acceptée**.
///

Le symbole triple-slash ///est utilisé pour indiquer le début et la fin d'un composant DSFR. Il est suivi du nom du composant (identifiant en anglais), d'un titre éventuel et de la liste des paramètres du composant. Le contenu inclus dans le composant est au format Markdown.

Le plugin dsfr_structure est responsable de la transformation de cette syntaxe en composants DSFR. Il doit être déclaré dans le fichier mkdocs.yml, comme indiqué dans la section Installation.

Remarque : Le plugin dsfr_structure se base sur le plugin Pymdownx Blocks Extensions pour étendre la syntaxe Markdown.

Liste des composants DSFR

Consultez la liste des composants DSFR ou parcourez le menu principal Composants pour découvrir les composants disponibles et leur syntaxe d'intégration.

Spécificités du thème

Bloc de citation

Le bloc de citation Markdown est transformé en un composant de mise en exergue du DSFR et non pas un composant de citation. Le format de mise en exergue semble plus adapté pour une documentation au format Markdown.

Le code suivant Markdown :

> Ceci est un bloc de citation.

est transformé en :

Tableau avec légende

Les tableaux Markdown sont automatiquement transformés en tableaux DSFR. Il est possible d'ajouter une légende au tableau en utilisant la syntaxe MultiMarkdown : ajoutez une ligne contenant le texte de la légende entre crochets [Légende du tableau] en dernière ligne du tableau.

Le code suivant Markdown :

| Nom | Prénom | Rôle |
| --- | ------ | ---- |
| Dupont | Jean | Développeur |
| Martin | Claire | Designer |
[Équipe projet]

est transformé en un tableau DSFR avec une légende :

Accessibilité des emojis

Les emojis présents dans le contenu Markdown sont automatiquement encapsulés dans des balises <span aria-hidden="true"> afin de ne pas être lus par les lecteurs d'écran. Cette transformation est réalisée côté client par le thème mkdocs-dsfr et ne nécessite aucune action de votre part.

Par exemple, le texte Bravo 🎉 sera rendu avec l'emoji masqué pour les technologies d'assistance, évitant ainsi une lecture parasite.

Liens externes et accessibilité

Les liens externes (ouverts dans un nouvel onglet via le plugin open-in-new-tab) reçoivent automatiquement un attribut aria-label indiquant le nom de domaine et la mention « Nouvelle fenêtre ». Cela permet aux utilisateurs de lecteurs d'écran de savoir que le lien s'ouvrira dans un nouvel onglet et vers quel site.

Par exemple, un lien vers https://www.ecologie.gouv.fr recevra automatiquement l'attribut aria-label="www.ecologie.gouv.fr — Nouvelle fenêtre".