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. Valeur booléenne qui permet d'afficher ou de masquer la date de la dernière révision de la page actuelle dans le pied de page. Vous pouvez la définir sur true pour afficher la date, ou sur false pour la masquer.

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.

links

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.

links

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.

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.

Plugins associés

Le thème est fourni avec plusieurs plugins.

Plugin dsfr_base

Ce plugin est obligatoire pour le fonctionnement du thème mkdocs-dsfr. Il gère l'affichage de la date de révision et d'autres fonctionnalités essentielles, notamment le lien entre les extensions markdown fourni par dsfr_structure et le thème mkdocs-dsfr. Aucune option spécifique n'est proposée par ce plugin.

Plugin tags_index

Ce plugin, facultatif, permet de générer une page d'index des tags utilisés dans la documentation. Il est recommandé d'utiliser ce plugin si vous utilisez des tags dans vos pages. Aucune option spécifique n'est proposée par ce plugin.

Plugin document_dates

Ce plugin, facultatif, permet d'afficher les dates de création et de modification des pages (basés sur l'horodatage Git) dans l'en-tête ou le pied de page. S'il est ajouté à la liste des plugins, alors, par défaut, les dates de création et de modification sont ajoutés aux articles, sauf la page d'accueil. Ce plugin propose une option de placement des dates position dont les valeurs possibles sont : bottom (par défaut, en fin d'article), top (en haut de l'article) ou disabled (désactivé, sauf si demandé dans l'entête de page Markdown). Les valeurs de position et de datation sont surchargeables par page via les métadonnées du front matter Markdown.

Consultez la mise en page pour plus de détails sur l'utilisation de ce plugin.