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.

Respect de la syntaxe

Les paramètres doivent avoir une indentation de 4 espaces pour être reconnus par le plugin dsfr_structure. Chaque déclaration de paramètre se trouve alors aligné avec le nom du composant.

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 :

Ceci est un bloc de citation.