Documentation du thème Mkdocs DSFR

Le composant mkdocs-dsfr est un thème pour Mkdocs permettant de créer une documentation conforme au DSFR, le système de design de l'Etat.

Avertissement

Ce thème est uniquement destiné à être utilisé pour les sites et applications officiels des services publics français. Son objectif principal est de faciliter l'identification des sites gouvernementaux pour les citoyens.

Prérequis

  • Python 3.10 ou supérieur
  • (Facultatif mais recommandé) : uv pour la gestion des paquets Python. Vous pouvez néanmoins utiliser pip si vous le souhaitez. Le guide de démarrage rapide ci-dessous utilise uv.

Démarrage rapide

Pour expérimenter rapidement mkdocs avec le DSFR, vous pouvez cloner le projet d'exemple, construit avec uv, un gestionnaire de paquets Python moderne et rapide.

Installation avec uv

  • Initialiser un nouveau projet avec uv
mkdir ma-doc-dsfr
cd ma-doc-dsfr
uv init
  • Installer la dépendance mkdocs-dsfr. Cette dépendance installera sur votre projet Mkdocs lui-même et toutes les dépendances nécessaires.
uv add mkdocs-dsfr
  • (Recommandé) Installer le plugin Open in a new tab afin de détecter les liens externes et de les ouvrir dans un nouvel onglet, avec une icône reconnaisable.
uv add mkdocs-open-in-new-tab
  • Modifier le fichier mkdocs.yml pour utiliser le thème dsfr. Ajouter les lignes suivantes en fin de fichier.
theme:
  name: dsfr
  locale: fr

plugins:
  - search:
      lang: fr
  - open-in-new-tab
  - tags_index
  - rss
  - git-revision-date-localized
  - dsfr_base

markdown_extensions:
  - dsfr_structure.extension.all_extensions
  - pymdownx.snippets
  - pymdownx.highlight:
      use_pygments: true
  - pymdownx.emoji:
      options:
        attributes:
          align: absmiddle
          height: 20px
          width: 20px
  - pymdownx.superfences
  - toc:
      permalink: false
      toc_depth: 2
  - attr_list
  - def_list
  - tables

La directive theme permet de spécifier le thème à utiliser. Dans ce cas, nous utilisons le thème dsfr. L'option locale permet de définir la langue de la documentation. C'est utile pour l'accessibilité de la page et le fonctionnement de certains plugins. Dans ce cas, nous utilisons le français (fr).

La directive plugins permet d'ajouter des plugins supplémentaires à Mkdocs. Dans ce cas, nous ajoutons le plugin search pour la recherche dans la documentation.

Enfin, la directive markdown_extensions permet d'ajouter des extensions Markdown supplémentaires. Dans ce cas, nous ajoutons plusieurs extensions pour améliorer la syntaxe Markdown et profiter pleinement du thème DSFR.

  • Lancer Mkdocs en mode développement. Ce mode permet de visualiser la documentation générée en temps réel.
uv run mkdocs serve
  • Pour construire la documentation, utilisez la commande suivante :
uv run mkdocs build

La documentation est alors créée dans le dossier site de votre projet. Félicitations, vous avez créé votre première documentation avec le thème DSFR ! Dans la section suivante, nous allons explorer les différentes options de configuration disponibles pour personnaliser votre documentation.

Options du thème DSFR

Dans votre fichier de configuration mkdocs.yml, vous pouvez définir les options de thème pour personnaliser votre site. Voici les options de thème disponibles et leurs valeurs par défaut :

theme:
  name: dsfr
  locale: fr
  # Configuration par défaut (modifiable)
  afficher_bouton_editer: true
  afficher_date_de_revision: false
  afficher_menu_lateral: true
  afficher_sommaire: false
  bouton_hautdepage: left
  include_search_page: true
  intitule: "République <br> française"
  libelle_bouton_editer: Éditer dans Gitlab Forge
  menu_lateral:
    mode: page
  header:
    titre: "Titre"
    sous_titre: "Sous-titre"
    logo_alt: ""
  footer:
    description: "Description à modifier"
    links:
      - name: legifrance.gouv.fr
        url: https://legifrance.gouv.fr
      - name: gouvernement.fr
        url: https://gouvernement.fr
      - name: service-public.fr
        url: https://service-public.fr
      - name: data.gouv.fr
        url: https://data.gouv.fr

Options du thème

name

Le nom du thème. Il doit être défini sur dsfr.

locale

La locale pour le thème. Il doit être défini sur fr pour le français.

afficher_bouton_editer

Afficher ou masquer le menu latéral. Définissez-le sur true ou false.

afficher_date_de_revision

Afficher la date de dernière révision du document, à partir de Git. Cela suppose que vous utilisez un dépôt Git pour gérer votre documentation. Si vous utilisez un autre système de gestion de version, cette option ne fonctionnera pas. De plus, vous devez ajouter le plugin git-revision-date-localizeddans la définition des plugins, sous search :

plugins:
  - search:
      lang: fr
  - git-revision-date-localized

afficher_menu_lateral

Afficher ou masquer le menu latéral sur l'ensemble de la documentation.

menu_lateral

Configuration avancée du menu latéral. Cette option accepte les sous-clés suivantes :

mode

Définir le mode d'affichage du menu latéral. Les valeurs possibles sont :

  • page (par défaut) : affiche le sommaire de la page courante, basé sur les titres de la page.
  • folder : affiche une navigation basée sur l'arborescence réelle des fichiers source du dossier courant (structure des dossiers dans docs/).

Exemple :

theme:
  name: dsfr
  afficher_menu_lateral: true
  menu_lateral:
    mode: folder

Pour plus de détails sur les modes du menu latéral, consultez la documentation du composant menu latéral.

afficher_sommaire

Afficher ou masquer le sommaire sur l'ensemble de la documentation. Le sommaire est un menu de navigation qui s'affiche en haut de chaque page, permettant de naviguer rapidement dans le contenu.

bouton_hautdepage

Définir la position du bouton de retour en haut de page, affiché pour les pages longues (de longueur supérieure à deux fois la hauteur de l'écran). Les valeurs possibles sont left, right ou false pour le désactiver.

include_search_page

afficher et utiliser la barre de recherche. C'est une option standard dans MkDocs.

libelle_bouton_editer

Personnaliser le libellé de bouton d'édition.

intitule

Cette option définit l'intitulé du ministère dans le logo de l'en-tête et du pied de page. Utilisez les balises <br> pour aller à la ligne en fonction de la charte de chaque ministère.

Options de l'en-tête avec header

titre

Définir le titre qui apparaît dans l'en-tête de la page.

Cette option vous permet de définir une liste de liens qui apparaîtront dans l'en-tête. Chaque lien doit être un dictionnaire avec des clés name, url, title (optionnel) et icon (optionnel). L'identifiant d'icône DSFR peut être trouvé sur la page des icônes DSFR. Par exemple, indiquer arrow-left-line pour afficher l'icône flèche gauche fr-icon-arrow-left-line.

logo_alt

Définir le texte alternatif pour le logo dans l'en-tête de la page. Utile pour l'accessibilité. Par défaut, chaine vide "".

logo_url

Définir l'URL relative ou absolue du logo dans l'en-tête de la page. Par défaut, aucun logo n'est affiché.

soustitre

Définir le sous-titre qui apparaît sous le titre dans l'en-tête de la page.

Options du pied de page avec footer

description

Définir une description qui apparaît dans le pied de page.

Déprécié

Cette option vous permet de définir une liste de liens qui apparaîtront dans le pied de page. Chaque lien doit être un dictionnaire avec des clés name et url.

Cette option est dépréciée et sera supprimée dans une future version. le DSFR n'autorise pas la personnalisation de ces liens de bas de page. Veuillez utiliser les autres liens de bas de page du DSFR avec bottom_links.

Cette option vous permet de définir une liste de liens qui apparaîtront dans le pied de page personnalisable DSFR. Chaque lien doit être un dictionnaire avec des clés name et url et icon (optionnel). L'identifiant d'icône DSFR peut être trouvé sur la page des icônes DSFR. Par exemple, indiquer arrow-left-line pour afficher l'icône flèche gauche fr-icon-arrow-left-line.

Menu de navigation principal

Comme tout document créé avec Mkdocs, le menu de navigation est défini dans le fichier mkdocs.yml sous la clé nav. Voici un exemple de configuration :

nav:
  - Accueil: index.md
  - Guide de démarrage: guide.md
  - Référence API: api.md
  - À propos: about.md

Pour en savoir plus sur la configuration du menu de navigation, consultez la documentation officielle de Mkdocs.

Composants DSFR

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.

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 :

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

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".

Composant Accordéon

Ce composant permet de créer un accordéon DSFR.

Accordéon simple

Composant

Contenu de mon Accordéon

  • Point 1
  • Point 2

Extrait de code

/// accordion | Intitulé 1
Contenu de mon Accordéon

- Point 1
- Point 2
///

Options de l'accordéon

Option Valeur par défaut Description
open false L'accordéon est-il ouvert au départ
markup h5 Niveau de titre du bouton accordéon (h1 à h6)

Exemple d'accordéon ouvert

Composant

Titre

Bloc de citation

Extrait de code

/// accordion | Intitulé 2
    open: true
##### Titre

> Bloc de citation
///

Exemple avec niveau de titre personnalisé (markup)

Composant

Cet accordéon utilise un <h3> comme titre pour respecter la hiérarchie de la page.

Extrait de code

/// accordion | Intitulé 3
    markup: h3
Cet accordéon utilise un `<h3>` comme titre pour respecter la hiérarchie de la page.
///

Composant Alerte

Ce composant permet de créer une alerte DSFR.

Alerte simple d'information

Composant

Information

C'est une Information importante.

Extrait de code

/// alert | Information
C'est une Information **importante**.
///

Options de l'alerte

Option Valeur par défaut Description
type info Type d'alerte. Valeurs possibles : success, error, info, warning
markup h5 Type de balise pour le titre. Valeurs possibles : "p", "h1", "h2", "h3", "h4", "h5", "h6"

Autres exemples d'alertes

Composant

alerte de succes

C'est une Information par defaut.

alerte d'erreur

C'est une Information d'erreur.

alerte d'info

C'est une Information.

alerte d'avertisssement

C'est une Information d'avertissement.

Avec puces
  • Toujours privilégier l’héritage des permissions.
  • Regrouper les documents nécessitant des droits spécifiques dans des bibliothèques distinctes.
  • Éviter de modifier les permissions directement sur des fichiers individuels.

Extrait de code

/// alert | alerte de succes
    type: success

C'est une Information **par défaut**.
///

/// alert | alerte d'erreur
    type: error

C'est une Information **d'erreur**.
///

/// alert | alerte d'info
    type: info

C'est une **Information**.
///

/// alert | alerte d'avertisssement
    type: warning

C'est une Information **d'avertissement**.
///

Composant Badge

Ce composant permet de créer un badge DSFR.

Badge simple d'information

Composant

Actualité

  • Dernière nouveauté

Extrait de code

/// badge
Actualité
///

- Dernière nouveauté

Options du badge

Option Valeur par défaut Description
type Type du badge. Valeurs possibles : success, error, info, warning, new. Si aucun, le type par défaut est gris.
icon true Affichage ou non de l'icône si un type est choisi.
color Couleur du badge, si aucun type choisi. A choisir dans la palette DSFR. Par exemple green-menthe

Autres exemples de badges

Composant

Validé

Périmé

Spécial

etc.

Extrait de code

/// badge
    type: success

Validé
///
/// badge
    type: error
    icon: false
Périmé
///
/// badge
    color: green-menthe
Spécial
///

etc.

Composant bandeau d'information importante

Ce composant permet de créer un bandeau d'information DSFR.

Élément unique

Comme le bandeau d'information est unique par page, il est déclaré dans les métadonnées du fichier Mardown source, et non comme un composant dans le contenu de la page.

Composant bandeau d'information

Dans l'en-tête du fichier Markdown, encadré par les symboles ---, ajoutez la section notice avec ses options. Si une option contient des caractères spéciaux comme :, encadrez votre libellé avec des guillemets pour éviter les erreurs de syntaxe.

---
... autres métadonnées...
notice:
  type: warning
  title: Attention
  description: "Voici l'exemple : un bandeau d'information importante"
  link_label: Lien si besoin
  link_url: https://example.com
  link_newtab: true
---

Cet extrait de code montre comment créer le bandeau visible sur cette page.

Options du bandeau

Option Valeur par défaut Description
type info Type de bandeau. Valeurs possibles : "info", "warning", "alert", "weather-orange", "weather-red", "weather-purple", "kidnapping", "cyberattack", "attack", "witness"
markup p Type de balise pour le texte du bandeau. Valeurs possibles : "p", "h1", "h2", "h3", "h4", "h5", "h6"
icon Icône à afficher dans le bandeau. Si vide, l'icône du type d'info est affichée.
link_label Texte du lien cliquable dans le bandeau. Si vide, aucun lien n'est affiché.
link_url URL du lien cliquable dans le bandeau.
link_newtab False Ouvre le lien cliquable dans un nouvel onglet.


Dépréciation du composant /// notice

Le composant /// notice est déprécié car il s'agit d'un élément unique de page à intégrer en en-tête. Ce composant sera supprimé dans la prochaine version, au profit de la métadonnée notice décrite ci-dessus.

Composant Carte

Ce composant permet de créer une carte DSFR.

Avertissement

Ce composant doit être encapsulé dans une grille DSFR (avec row et col) pour être affiché correctement.

Cartes sur deux colonnes

Composant

Exemple de carte

Une description succincte

Exemple de carte 2

Une autre description succincte

Extrait de code

/// row
/// col
/// card | Exemple de carte
    image: ../assets/placeholder.16x9.png
    target: https://www.example.com/
Une description succincte
///
///
/// col
/// card | Exemple de carte 2
    image: ../assets/placeholder.16x9.png
    target: https://www.example.com/
Une autre description succincte
///
///
///

Options de la carte

Option Valeur par défaut Description
description Description de la carte.
markup h5 Type de balise pour le titre. Valeurs possibles : "p", "h1", "h2", "h3", "h4", "h5", "h6"
badge Badge(s) associé(s) la carte. Les badges sont séparés par des virgules. Chaque badge nécessite un titre et éventuellement un code couleur sous la forme titre | code_couleur. Les valeurs success, error, info, warning, new peuvent aussi être utilisées à la place de la couleur.
tag Tag(s) associé(s) à la carte. Incompatible avec l'option badge. Les tags sont séparés par des virgules. Chaque tag nécessite un titre et éventuellement un code couleur sous la forme titre | code_couleur. Les valeurs success, error, info, warning, new peuvent aussi être utilisées à la place de la couleur.
enlarge True Si true, agrandit la zone de clic à toute la carte
target Lien de la carte.
target_new False Si true, ouvre le lien dans un nouvel onglet.
image Lien de l'image de la carte.
image_alt Texte alternatif de l'image de la carte.
download False Si true, passe la carte en mode téléchargement
lang Ajoute l'attribut hreflang au lien, pour définir la langue du document lié (Ex: 'fr')
assess False Si true, évaluation automatique des détails du fichier à télécharger (poids, format, etc.).
horizontal False Si true, passe la carte en mode horizontal.
horizontal_pos "" Position de l'image dans la carte horizontale. Valeurs possibles : tier ou half. Si rien, rapport 40/60
variations "" Variations de la carte. Valeurs possibles : grey, no-border, no-background, shadow. Si rien, pas de variation.

Autres exemples de cartes

Composant

Lien interne Avec Description

Description / sous-titre

Lien interne vers le composant badge

Juste le titre cliquable

Une autre description succincte

Avec badge

  • Défaut

  • Favori

Une autre description succincte

Mode download avec infos PJ

Sans image

Une autre description succincte

etc.

Extrait de code

/// row | fr-grid-row--gutters
/// col
/// card | Avec Description
    description: Description / sous-titre
    image: ../assets/placeholder.16x9.png
    target: https://www.example.com/
Une description succincte
///
///
/// col
/// card | Juste le titre cliquable
    image: ../assets/placeholder.16x9.png
    target: https://www.example.com/
    enlarge: false
Une autre description succincte
///
///
/// col
/// card | Avec badge
    image: ../assets/placeholder.16x9.png
    target: https://www.example.com/
    badge: Défaut, Favori | green-menthe
Une autre description succincte
///
///
///
/// row | fr-grid-row--gutters
/// col
/// card | Mode download avec infos PJ
    image: ../assets/placeholder.16x9.png
    target: /assets/placeholder.16x9.png
    download: true
    assess: true
///
///
/// col
/// card | Sans image
    target: https://www.example.com/
    horizontal: true
    horizontal_pos: half
Une autre description succincte
///
///
///

etc.

Composant Citation

Ce composant permet de créer une citation DSFR.

Citation simple

« Notre devise est : Liberté, Egalité, Fraternité ! Victor Hugo décrivait notre devise comme étant les trois marches du perron suprême et que le mot le plus fort était celui de Fraternité »

Victor Hugo

Extrait de code

/// quote | Victor Hugo
    image: https://upload.wikimedia.org/wikipedia/commons/thumb/2/25/Victor_Hugo_001.jpg/330px-Victor_Hugo_001.jpg
    size: lg
    color: green-menthe
« Notre devise est : Liberté, Egalité, Fraternité ! Victor Hugo décrivait notre devise comme étant les trois marches
du perron suprême et que le mot le plus fort était celui de Fraternité »
///

Options de la citation

Option Valeur par défaut Description
color Couleur utilisée pour la citation, si aucun type choisi. A choisir dans la palette DSFR. Par exemple green-menthe
size md Taille d'affichage du composant. A choisir parmi "md" (par défaut), "lg" ou "xl"
image Image à afficher. Si vide, pas d'image.

Composant fil d'Ariane

Ce composant permet de créer un fil d'Ariane DSFR.

Élément unique

Comme le fil d'Ariane est unique par page, il est déclaré dans les métadonnées du fichier Mardown source, et non comme un composant dans le contenu de la page.

Déclaration du fil d'Ariane

Dans l'en-tête du fichier Markdown, encadré par les symboles ---, ajoutez la section breadcrumb avec les titres et URLs des pages :

---
... autres métadonnées ...
breadcrumb:
  - Accueil: /
  - Composants: /composants/
  - Fil d'Ariane
---

Pour chaque item du fil d'Ariane, vous devez fournir le titre et l'URL relative, sauf pour le dernier item qui est la page actuelle et n'a pas de lien.

Si votre titre contient des caractères spéciaux comme :, encadrez votre libellé avec des guillemets pour éviter les erreurs de syntaxe.

Un exemple de page minimale avec un fil d'Ariane, et un item avec un caractère spécial :

---
breadcrumb:
  - Accueil: /
  - "Composants DSFR : détails": /composants/
  - Fil d'Ariane
---

# Le composant fil d'Ariane

Ce composant permet de créer un [fil d'Ariane DSFR](https://www.systeme-de-design.gouv.fr/version-courante/fr/composants/fil-d-ariane). Il est généralement utilisé pour indiquer la hiérarchie des pages dans une application ou un site web.

Le système de grille

Le système de grille est une notion centrale pour le DSFR. Si une documentation basique en Markdown n'a pas besoin de cette grille, il est important de la connaître pour les pages plus complexes, avec textes sur plusieurs colonnes, cartes ou tuiles.

La notation utilisée est celle du DSFR, veuillez consulter la documentation officielle pour plus de détails.

Texte sur deux colonnes

Composant

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.

Extrait de code

/// row
/// col
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
///
/// col
Sed ut perspiciatis unde omnis iste natus error sit voluptatem accusantium doloremque laudantium, totam rem aperiam, eaque ipsa quae ab illo inventore veritatis et quasi architecto beatae vitae dicta sunt explicabo. Nemo enim ipsam voluptatem quia voluptas sit aspernatur aut odit aut fugit, sed quia consequuntur magni dolores eos qui ratione voluptatem sequi nesciunt. Neque porro quisquam est, qui dolorem ipsum quia dolor sit amet, consectetur, adipisci velit, sed quia non numquam eius modi tempora incidunt ut labore et dolore magnam aliquam quaerat voluptatem.
///
///

Options de la grille

Options de row

row n'a pas besoin de paramètres par défaut. Cependant, il est possible d'ajouter des classes supplémentaires DSFR pour la définition de row. Ainsi pour mettre en place les gouttières sur une row, vous pouvez utiliser la classe fr-grid-row--gutters :

/// row | fr-grid-row--gutters
...
///
Option Valeur par défaut Description
halign Alignement horizontal de la grille. Peut être left, center ou right.
valign Alignement vertical de la grille. Peut être top, middle ou bottom.

Options de col

col n'a pas besoin de paramètres par défaut. Pour définir les différentes classes de largeur d'une colonne, il suffit de les spécifier en paramètres, sans le préfixe fr-col-, séparés par un espace. Par exemple pour définir une colonne de 12 par défaut et 4 en mode large :

/// col | 12 lg-4
///
Option Valeur par défaut Description
class Classes supplémentaires à ajouter à la colonne.

Exemple avec spéficications de largeurs

  • Composant

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

Tuile succès

Une autre description succincte

  • Extrait de code
/// row | fr-grid-row--gutters
    valign: bottom
/// col | 12 lg-8
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
///
/// col | 12 lg-4
/// tile | Tuile succès
    picto: system/success
    target: https://www.example.com/
Une autre description succincte
///
///
///

Composant lettre d'information et réseaux sociaux

Ce composant permet de créer une lettre d'information et réseaux sociaux DSFR.

En bas de cette page, un exemple complet est affiché.

Composant lettre d'information et réseaux sociaux

Dans l'en-tête du fichier Markdown, encadré par les symboles ---, ajoutez la section newsletter avec ses options. Si une option contient des caractères spéciaux comme :, encadrez votre libellé avec des guillemets pour éviter les erreurs de syntaxe.

---
... autres métadonnées...
newsletter:
  title: Titre de la lettre d'information et réseaux sociaux
  description: Description de la lettre d'information et réseaux sociaux pour inciter à l'inscription.
  button: S'abonner (lien fictif)
  button_url: https://example.com
  social_title: Titre réseaux sociaux
  rss: true
  social:
    - nom: facebook
      url: https://facebook.com
    - nom: twitter-x
      url: https://twitter.com
    - nom: linkedin
      url: https://linkedin.com
    - nom: youtube
      url: https://youtube.com
    - nom: instagram
      url: https://instagram.com
---

Cet extrait de code montre comment créer le composant visible sur cette page.

Options du bandeau

Option Valeur par défaut Description
title Titre de la lettre d'information et réseaux sociaux.
description Description de la lettre d'information et réseaux sociaux pour inciter à l'inscription.
button Texte du bouton d'inscription à la lettre d'information.
button_url URL du bouton d'inscription à la lettre d'information.
social_title Titre de la section des réseaux sociaux.
rss False Affiche l'icône RSS si vrai, permettant de s'abonner aux modifications du site grâce au plugin mkdocs-rss-plugin.
social Liste des réseaux sociaux à afficher, avec prropiétés "nom" et "url". Les noms possibles sont : "facebook", "twitter-x", "linkedin", "youtube", "instagram".

Dépréciation des options de thème newsletter

Les options de thème newsletter sont dépréciées au profit de cette métadonnée permettant d'afficher ce composant uniquement sur les pages souhaitées.

Composant Médias

Ce composant permet de créer un contenu médias DSFR. Il supporte les types de médias suivants : vidéo, vidéo externe (iframe YouTube, Dailymotion, etc.), audio et image.

Vidéo

Le type video permet d'intégrer une vidéo hébergée directement accessible par URL.

Composant

L'outro du MATTE

Extrait de code

/// media | L'outro du MATTE
    url: ../../assets/MIN_SG_16-9_1.mp4
    captions: ../../assets/MIN_SG_16-9_1.vtt
    poster: ../../assets/MIN_SG_16-9_1.png
///

Vidéo externe (iframe)

Le type video_external permet d'intégrer une vidéo hébergée sur une plateforme tierce (YouTube, Dailymotion, Peertube, etc.) via une iframe.

Composant

Présentation du Système de Design de l'État

Extrait de code

/// media | Présentation du Système de Design de l'État
    type: video_external
    url: https://www.youtube.com/embed/HyirpmPL43I
    ratio: 16x9
///
URL d'intégration

Pour les vidéos YouTube, utilisez l'URL d'intégration (format https://www.youtube.com/embed/ID_VIDEO) et non l'URL de partage classique.

Audio

Le type audio permet d'intégrer un fichier audio avec un lecteur natif.

Composant

Extrait audio de démonstration

Extrait de code

/// media | Extrait audio de démonstration
    type: audio
    url: ../../assets/example-audio.mp3
///

Image

Le type image permet d'intégrer une image dans un composant de contenu médias DSFR, avec une légende et un cadre conforme au DSFR.

Composant

Vue du bâtiment du ministère
Photographie du ministère — Source : MTECT

Extrait de code

/// media | Photographie du ministère — Source : MTECT
    type: image
    url: ../../assets/placeholder.16x9.png
    title: Vue du bâtiment du ministère
///

Légende avec lien

Tous les types de médias supportent l'ajout d'un lien dans la légende, via les options link et link_label.

Composant

L'outro du MATTEEn savoir plus sur le ministère

Extrait de code

/// media | L'outro du MATTE
    url: ../../assets/MIN_SG_16-9_1.mp4
    poster: ../../assets/MIN_SG_16-9_1.png
    link: https://www.ecologie.gouv.fr
    link_label: En savoir plus sur le ministère
///

Ratio d'affichage

L'option ratio permet de définir le ratio d'affichage du média. Par défaut, le ratio est 16x9. Voici un exemple avec un ratio 4x3 :

/// media | Image au format 4x3
    type: image
    url: ../../assets/placeholder.16x9.png
    ratio: 4x3
///

Options de médias

L'argument à côté du mot-clé media est la légende du média. Il est affiché en dessous du média dans un élément figcaption.

Option Valeur par défaut Description
type video Type de média : video, video_external, audio ou image.
url URL du média à afficher.
title Titre du média, utilisé comme attribut title pour les iframes et comme texte alternatif (alt) pour les images. Si non renseigné, la légende est utilisée à la place.
ratio 16x9 Ratio d'affichage du média. Valeurs possibles : 16x9, 4x3, 1x1, 32x9, 3x2, 3x4, 2x3.
poster Vidéo uniquement : image de prévisualisation affichée avant le chargement de la vidéo.
captions Vidéo uniquement : URL du fichier de sous-titres (format .vtt).
link URL d'un lien ajouté à la légende du média.
link_label Libellé du lien dans la légende. Si non renseigné, l'URL du lien est affichée.

Menu latéral

L'option du thème afficher_menu_lateral permet d'afficher ou de masquer le menu latéral sur l'ensemble de la documentation. Par défaut, il est activé.

theme:
  name: dsfr
  locale: fr
  afficher_menu_lateral: true
  ... # autres options du thème

Il est possible de désactiver (ou inversement, activer) le menu latéral pour une page spécifique en utilisant la métadonnée sidemenu en en-tête du fichier Markdown de la page concernée.

---
sidemenu: false
---

# Titre de la page

Contenu de la page sans menu latéral.


Dépréciation de la métadonnée template

L'utilisation de la métadonnée template (avec comme valeur main_no_lateral.html ou main_lateral.html) pour désactiver le menu latéral est dépréciée, et sera supprimée prochainement. Il est recommandé d'utiliser sidemenu à la place, comme indiquée ci-dessus.

Mode d'affichage du menu latéral

Le menu latéral peut fonctionner selon deux modes : page (par défaut) et dossier.

Mode page (par défaut)

En mode page, le menu latéral affiche le sommaire de la page courante, basé sur les titres de la page (table des matières). C'est le comportement par défaut.

Mode dossier

En mode folder, le menu latéral affiche une navigation basée sur l'arborescence réelle des fichiers source de la documentation (les dossiers dans docs/). Les pages qui partagent un même dossier parent sont regroupées dans le menu latéral, ce qui permet de naviguer entre les pages voisines sans passer par le menu principal. Les titres affichés dans le menu sont les titres réels des pages.

Les pages situées à la racine de docs/ (sans sous-dossier) ne bénéficient pas du mode dossier : le menu latéral revient automatiquement au mode page (sommaire de la page courante). Les éventuels sous-dossiers sont affichés sous forme de sous-menus dépliables.

Pour activer le mode dossier de manière globale, ajoutez la configuration menu_lateral dans les options du thème :

theme:
  name: dsfr
  locale: fr
  afficher_menu_lateral: true
  menu_lateral:
    mode: folder

Il est également possible de définir le mode du menu latéral pour une page spécifique en utilisant la métadonnée sidemenu_mode en en-tête du fichier Markdown :

---
sidemenu: true
sidemenu_mode: folder
---

# Titre de la page

Contenu de la page avec un menu latéral en mode dossier.
Plugin dsfr_base requis

Le mode dossier nécessite le plugin dsfr_base pour construire l'arborescence de navigation. Assurez-vous qu'il est bien déclaré dans la liste des plugins de votre fichier mkdocs.yml.

Les valeurs possibles pour sidemenu_mode et menu_lateral.mode sont :

Valeur Description
page Affiche le sommaire de la page courante (titres de la page). Comportement par défaut.
folder Affiche la navigation basée sur l'arborescence des fichiers source du dossier courant (structure des dossiers dans docs/).

Composant mise en avant

Ce composant permet de créer une mise en avant DSFR.

Mise en avant simple

Avec icône

Information importante

C'est une mise en avant importante.

Extrait de code

/// callout | Information importante
C'est une mise en avant **importante**.
///

Options de la mise en avant

Option Valeur par défaut Description
color Couleur du badge, si aucun type choisi. A choisir dans la palette DSFR. Par exemple green-menthe
markup p Type de balise pour le titre. Valeurs possibles : "p", "h1", "h2", "h3", "h4", "h5", "h6"
icon Icône à afficher. Si vide, pas d'icône.
link_label Texte du lien cliquable dans le bandeau. Si vide, aucun lien n'est affiché.
link_url URL du lien cliquable dans le bandeau.
link_newtab False Ouvre le lien cliquable dans un nouvel onglet.

Autres exemples de mises en avant

Avec icône

Information importante

C'est une mise en avant importante.

Extrait de code

/// callout | Information importante
    icon: info-line
C'est une mise en avant **importante**.
///

Avec bouton

Information importante

C'est une mise en avant importante.

En savoir plus

Extrait de code

/// callout | Information importante
    link_label: En savoir plus
    link_url: https://www.example.com/
    link_newtab: true
C'est une mise en avant **importante**.
///

Diverses personnalisations

Information importante

C'est une mise en avant importante.

En savoir plus

Extrait de code

/// callout | Information importante
    markup: h5
    color: green-menthe
    icon: medal-fill
    link_label: En savoir plus
    link_url: https://www.example.com/
    link_newtab: true
C'est une mise en avant **importante**.
///

Composant Onglet

Ce composant permet de créer un système d'onglets DSFR.

Le système d'onglets se compose de deux blocs imbriqués :

  • tabs : le conteneur global du système d'onglets
  • tab : chaque onglet individuel, avec son libellé et son contenu

Onglets simples

Composant

Contenu du premier onglet.

  • Point 1
  • Point 2

Contenu du deuxième onglet.

Contenu du troisième onglet.

Extrait de code

/// tabs

/// tab | Onglet 1
Contenu du **premier** onglet.

- Point 1
- Point 2
///

/// tab | Onglet 2
Contenu du *deuxième* onglet.
///

/// tab | Onglet 3
Contenu du troisième onglet.
///

///

Options du conteneur tabs

Option Valeur par défaut Description
label Système d'onglets Libellé accessible du système d'onglets (attribut aria-label de la liste d'onglets)
viewport_width false Si true, le système d'onglets prend toute la largeur de la fenêtre

Options de chaque tab

Option Valeur par défaut Description
selected false Si true, l'onglet est sélectionné par défaut. Le premier onglet est automatiquement sélectionné si aucun n'est explicitement marqué
icon Icône Remix Icon à afficher à gauche du libellé de l'onglet (ex: checkbox-circle-line). Le préfixe fr-icon- est ajouté automatiquement

Exemples avancés

Onglets avec libellé accessible personnalisé

Composant

Les dernières actualités du projet.

Accédez à la documentation technique.

Extrait de code

/// tabs
    label: Navigation par catégorie

/// tab | Actualités
Les dernières actualités du projet.
///

/// tab | Documentation
Accédez à la documentation technique.
///

///

Onglets avec icônes

Composant

Contenu de l'onglet Accueil.

Contenu de l'onglet Paramètres.

Contenu de l'onglet Notifications.

Extrait de code

/// tabs

/// tab | Accueil
    icon: home-4-line
Contenu de l'onglet Accueil.
///

/// tab | Paramètres
    icon: settings-5-line
Contenu de l'onglet Paramètres.
///

/// tab | Notifications
    icon: notification-3-line
Contenu de l'onglet Notifications.
///

///

Onglet sélectionné par défaut

Composant

Contenu du premier onglet.

Cet onglet est sélectionné par défaut.

Contenu du troisième onglet.

Extrait de code

/// tabs

/// tab | Premier
Contenu du premier onglet.
///

/// tab | Deuxième
    selected: true
Cet onglet est sélectionné par défaut.
///

/// tab | Troisième
Contenu du troisième onglet.
///

///

Pleine largeur de la fenêtre

Composant

Ce système d'onglets prend toute la largeur de la fenêtre.

Deuxième panneau en pleine largeur.

Extrait de code

/// tabs
    viewport_width: true

/// tab | Onglet large 1
Ce système d'onglets prend toute la largeur de la fenêtre.
///

/// tab | Onglet large 2
Deuxième panneau en pleine largeur.
///

///

Sommaire

Ce composant permet de créer un sommaire DSFR.

Élément unique

Comme le sommaire est unique par page, il est déclaré dans les métadonnées du fichier Mardown source, et non comme un composant dans le contenu de la page.

Déclaration du sommaire

Par défaut, le sommaire n'est pas présent dans chaque page. Pour l'activer globalement, vous pouvez ajouter l'option afficher_sommaire: true dans le fichier mkdocs.yml de votre projet. Référez-vous à la liste des options de configuration pour en savoir plus.

Pour activer (ou désactiver) le sommaire uniquement sur certaines pages, dans l'en-tête du fichier Markdown, encadré par les symboles ---, ajoutez la section summary en précisant True(ou False) :

---
... autres métadonnées ...
summary: True
---

Exemple de déclaration

Dans l'exemple ci-dessous, le sommaire est activé et affichera tous les titres de niveau 2 et 3 de la page :

---
summary: True
---

# Ma page avec différents titres

Début de texte

## Titre de niveau 2

### Titre de niveau 3

Texte après le titre de niveau 3

## Titre de niveau 2-bis

Composant Tuile

Ce composant permet de créer une tuile DSFR.

Avertissement

Ce composant doit être encapsulé dans une grille DSFR (avec row et col) pour être affiché correctement.

Tuiles sur deux colonnes

Composant

Exemple de tuile

Une description succincte

Exemple de tuile 2

Une autre description succincte

Extrait de code

/// row | fr-grid-row--gutters
/// col
/// tile | Exemple de tuile
    picto: digital/application
    target: https://www.example.com/
Une description succincte
///
///
/// col
/// tile | Exemple de tuile 2
    picto: environment/food
    target: https://www.example.com/
Une autre description succincte
///
///
///

Options de la tuile

Option Valeur par défaut Description
description Description de la tuile.
markup h5 Type de balise pour le titre. Valeurs possibles : "p", "h1", "h2", "h3", "h4", "h5", "h6"
badge Badge associé la tuile. Nécessite un titre et éventuellement un code couleur sous la forme titre | code_couleur. Les valeurs success, error, info, warning, new peuvent aussi être utilisées à la place de la couleur.
tag Tag associé à la tuile. Incompatible avec l'option badge. Nécessite un titre et éventuellement un code couleur sous la forme titre | code_couleur. Les valeurs success, error, info, warning, new peuvent aussi être utilisées à la place de la couleur.
enlarge True Si true, agrandit la zone de clic à toute la tuile
target Lien de la tuile.
target_new False Si true, ouvre le lien dans un nouvel onglet.
picto Identifiant la picto DSFR. Les pictogrammes se trouvent dans le dossier artwork du paquetage DSFR. Renseigner le chemin sous la forme thematique/picto (sans l'extension .svg)
download False Si true, passe la tuile en mode téléchargement
lang Ajoute l'attribut hreflang au lien, pour définir la langue du document lié (Ex: 'fr')
assess False Si true, évaluation automatique des détails du fichier à télécharger (poids, format, etc.).
horizontal False Si true, passe la tuile en mode horizontal.
vertical_breakpoint Point de rupture pour passer en mode vertical. Par défaut, aucun. Valeurs possibles : md ou lg
variations "" Variations de la tuile. Valeurs possibles : grey, no-border, no-background, shadow. Si rien, pas de variation.

Autres exemples de tuiles

Composant

Avec Description

Description / sous-titre

Une description succincte

Juste le titre cliquable

Une autre description succincte

Avec badge

Une autre description succincte

Favori

Mode download avec infos PJ

Mode horizontal 50%

Une autre description succincte

etc.

Extrait de code

/// row | fr-grid-row--gutters
/// col
/// tile | Avec Description
    description: Description / sous-titre
    picto: digital/internet
    target: https://www.example.com/
Une description succincte
///
///
/// col
/// tile | Juste le titre cliquable
    picto: health/health
    target: https://www.example.com/
    enlarge: false
Une autre description succincte
///
///
/// col
/// tile | Avec badge
    picto: institutions/firefighter
    target: https://www.example.com/
    badge: Favori | green-menthe
Une autre description succincte
///
///
///
/// row | fr-grid-row--gutters
/// col
/// tile | Mode download avec infos PJ
    picto: environment/leaf
    target: /assets/placeholder.16x9.png
    download: true
    assess: true
///
///
/// col
/// tile | Mode horizontal 50%
    picto: system/success
    target: https://www.example.com/
    horizontal: true
Une autre description succincte
///
///
///

etc.

Mise en page avec le thème mkdocs-dsfr

La mise en page avec le thème mkdocs-dsfr se base sur une mise en page standard du DSFR :

  • Un en-tête avec le logo du ministère, le titre, le sous-titre, et une barre de recherche ;
  • Un menu de navigation conforme au DSFR ;
  • Un contenu principal avec des sections et des sous-sections ;
  • Un menu latéral pour la navigation dans le contenu.
  • Un pied de page avec des informations de contact et des liens.

Les composants optionnels de mise en page

Le thème mkdocs-dsfr permet d'ajouter des composants optionnels de mise en page. Ce sont des composants DSFR qui n'apparaissent qu'une fois par page, à une place prédéfinie. Vous pouvez consulter la liste des composants uniques par page pour les ajouter.

Configuration d'un composant unique par page

Les composants uniques par page sont configurés dans les métadonnées du fichier Markdown de la page. Voici un exemple de configuration pour le menu latéral, le fil d'Ariane et le sommaire :

---
sidemenu: true
breadcrumb:
  - Accueil: /
  - Composants: /composants/
  - Fil d'Ariane
summary: true
---

# Titre de la page

Contenu de la page avec le menu latéral, le fil d'Ariane et le sommaire.

Consultez la documentation de chaque composant unique par page pour connaitre sa configuration.

Le système de grille

Le thème mkdocs-dsfr utilise un système de grille basé sur le DSFR pour organiser le contenu sur plusieurs colonnes. Consultez la documentation du composant grille pour en savoir plus sur sa configuration.

Paramètres d’affichage

Choisissez un thème pour personnaliser l’apparence du site.