Material

Material for MkDocs est le thème le plus populaire pour ProperDocs/MkDocs.

Installation

pip install mkdocs-material

Configuration de base

theme:
  name: material
  language: fr
  palette:
    - scheme: default
      primary: deep purple
      accent: deep orange
  font:
    text: Roboto
    code: Roboto Mono
  favicon: favicon.png
  icon:
    logo: material/bat

Mode sombre / clair

Material supporte le basculement automatique selon les préférences système :

theme:
  palette:
    # Mode clair
    - media: "(prefers-color-scheme: light)"
      scheme: default
      primary: deep purple
      accent: deep orange
      toggle:
        icon: material/brightness-7
        name: Passer en mode sombre

    # Mode sombre
    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      primary: teal
      accent: purple
      toggle:
        icon: material/brightness-4
        name: Passer en mode clair

Scheme	Description
`default`	Mode clair
`slate`	Mode sombre

Couleurs principales

Les couleurs primary et accent sont au format kebab-case :

Red Pink Purple Deep Purple Indigo Blue Light Blue Cyan Teal Green Light Green Orange Deep Orange Brown Grey Blue Grey

Polices

theme:
  font:
    text: Roboto        # Police du texte
    code: Roboto Mono   # Police du code

Polices disponibles pour text : Roboto, Roboto Slab, Source Sans Pro, Helvetiva Neue...

theme:
  features:
    - navigation.instant        # Navigation SPA (pas de rechargement)
    - navigation.instant.progress  # Barre de progression
    - navigation.tracking       # URL suit la section visible
    - navigation.tabs           # Onglets de premier niveau
    - navigation.path           # Fil d'Ariane
    - navigation.top            # Bouton "Retour en haut"
    - navigation.sections       # Sections dépliables
    - navigation.indexes        # Pages index par dossier
    - navigation.footer         # Liens précédent/suivant
    - navigation.expand         # Déplier la nav automatiquement
    - search.suggest            # Autocomplétion recherche
    - search.highlight          # Surbrillance dans les résultats
    - content.code.copy         # Bouton copier sur les blocs de code
    - header.autohide           # Header qui disparaît au scroll

Icônes d'admonitions

theme:
  icon:
    admonition:
      note: octicons/tag-16
      info: octicons/info-16
      tip: octicons/squirrel-16
      warning: octicons/alert-16
      danger: octicons/zap-16
      example: octicons/beaker-16

CSS personnalisé

Pour aller au-delà de la configuration YAML, ajoutez un fichier CSS :

extra_css:
  - css/custom.css

/* docs/css/custom.css */
.md-header {
    background-color: var(--md-primary-fg-color);
}