MkDocs Cheatsheet

Introduction

MkDocs est un générateur de site de documentation statique écrit en Python. Il utilise Markdown pour créer des sites de documentation professionnels et attrayants.

Installation

pip install mkdocs

Commandes principales

  • mkdocs new [dir-name] - Créer un nouveau projet
  • mkdocs serve - Démarrer le serveur de documentation en mode live-reload
  • mkdocs build - Générer le site de documentation
  • mkdocs -h - Afficher l'aide

Configuration de base

Le fichier mkdocs.yml est le fichier de configuration principal :

site_name: Mon Site de Documentation
theme:
  name: material
nav:
  - Accueil: index.md
  - Guide: guide.md
  - API: api.md

Structure de projet recommandée

mon-projet/
├── docs/
│   ├── index.md          # Page d'accueil
│   ├── guide.md          # Guide utilisateur
│   ├── api.md            # Documentation API
│   └── assets/           # Fichiers statiques (images, CSS)
│       ├── images/       # Images
│       └── styles.css    # Styles personnalisés
└── mkdocs.yml            # Fichier de configuration

Thèmes

MkDocs supporte plusieurs thèmes :

  • mkdocs (thème par défaut)
  • readthedocs (thème ReadTheDocs)
  • material (thème Material pour MkDocs - le plus populaire)

Pour utiliser le thème Material :

theme:
  name: material
  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - toc.integrate
    - search.suggest
    - search.highlight
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/weather-night
        name: Mode sombre
    - scheme: slate
      primary: red
      accent: red
      toggle:
        icon: material/weather-sunny
        name: Mode clair

Extensions Markdown

MkDocs supporte les extensions Markdown suivantes :

  • tables : Pour les tableaux
  • fenced_code : Blocs de code avec syntaxe
  • codehilite : Colorisation syntaxique
  • toc : Table des matières
  • meta : Métadonnées dans les fichiers Markdown

Plugins utiles

  • mkdocs-material : Thème Material
  • mkdocs-with-pdf : Export en PDF
  • mkdocs-autodoc : Documentation automatique à partir du code
  • mkdocs-macros-plugin : Macros et variables

Bonnes pratiques

  1. Organisation : Organisez votre documentation en sections logiques
  2. Navigation : Utilisez une structure de navigation claire dans mkdocs.yml
  3. Liens : Utilisez des liens relatifs pour les fichiers internes
  4. Images : Placez les images dans un dossier dédié (docs/assets/images/)
  5. Mise à jour : Mettez à jour régulièrement votre documentation

Exemple complet

site_name: Mon Application
site_url: https://example.com
repo_url: https://github.com/user/repo
repo_name: user/repo
edit_uri: edit/main/docs/

theme:
  name: material
  language: fr
  features:
    - navigation.tabs
    - navigation.tabs.sticky
    - toc.integrate
    - search.suggest
    - search.highlight
  palette:
    - scheme: default
      primary: blue
      accent: blue
    - scheme: slate
      primary: blue
      accent: blue

nav:
  - Accueil: index.md
  - Installation: installation.md
  - Configuration: configuration.md
  - Utilisation: utilisation.md
  - API: api.md
  - Contribuer: contribuer.md

markdown_extensions:
  - pymdownx.highlight
  - pymdownx.superfences
  - pymdownx.snippets
  - pymdownx.tabbed
  - pymdownx.emoji
  - pymdownx.tasklist
  - pymdownx.tilde
  - pymdownx.critic
  - pymdownx.keys
  - pymdownx.details
  - pymdownx.mark

Dépannage

  • Problème de compilation : Vérifiez la syntaxe YAML dans mkdocs.yml
  • Images non affichées : Vérifiez les chemins relatifs
  • Navigation non fonctionnelle : Vérifiez les entrées dans la section nav
  • Extensions non reconnues : Installez les extensions nécessaires avec pip