Créer un site web facilement avec MkDocs

PyLadiesCon 2025 - 6 décembre 2025

Françoise CONIL, Ingénieure d’études CNRS, Laboratoire LIRIS Lyon

MkDocs

MkDocs est un générateur de sites statiques orientés documentation de projet.

C’est la description sur la page d’accueil MkDocs.

Présentation

MkDocs créé par Tom Christie pour la documentation de Django REST Framework

• générer la documentation à partir de sources Markdown
• bénéficier des capacités de visualisation des éditeurs comme SublimeText
• projet indépendant depuis 2014 ¹
• documentation claire
• très largement utilisé ²

Mon usage : rassembler des notes plutôt basiques mais j’ai découvert qu’il était plus riche que je pensais (avec Material).

À l’heure où les outils deviennent de plus en plus complexes, MkDocs est un générateur de sites statiques qui reste très simple à comprendre et à utiliser. de sources Markdown.

capacités de visualisation, de rendu immédiat des éditeurs comme SublimeText

L’outil faisait partie du code de Django REST Framework, il a été publié en tant que projet indépendant en 2014.

1. Présentation “Documenting your project with MkDocs” de Tom Christie à EuroPython 2014

2. 91.1k projets avec un fichier mkdocs.yml sur GitHub

Facilité de mise en oeuvre

Installer MkDocs dans un environnement virtuel, isolé des packages systèmes.

1. pip install mkdocs
2. mkdocs new my-site
3. cd my-site
4. mkdocs serve

Fonctions intégrées

• greffon de recherche (lunr.js)
• serveur web avec rechargement automatique

1. Le serveur supporte le live reload et reconstruit la documentation à chaque modification : fichiers source, fichier de configuration, thème, …
2. Exécuter mkdocs serve dans le dossier du fichier mkdocs.yml.
3. Greffon de recherche intégré basé sur le moteur de recherche lunr.js

Plugin : Greffon (Office québécois de la langue française), extension

Créer un environnement virtuel

lunr.js permet la mise en place de fonctionnalité de recherche sans recourir à un service externe.

Structure générée

Le contenu du projet généré est simple.

Fichier de configuration : mkdocs.yml

site_name: My Docs

Dossier docs pour les fichiers sources

$ tree -a
.
├── docs
│   └── index.md
└── mkdocs.yml

1 directory, 2 files

Page d’accueil : index.md

# Welcome to MkDocs

For full documentation visit [mkdocs.org](https://www.mkdocs.org).

## Commands

* `mkdocs new [dir-name]` - Create a new project.
* `mkdocs serve` - Start the live-reloading docs server.
* `mkdocs build` - Build the documentation site.
* `mkdocs -h` - Print help message and exit.

## Project layout

    mkdocs.yml    # The configuration file.
    docs/
        index.md  # The documentation homepage.
        ...       # Other markdown pages, images and other files.

Ajout de pages

Ajouter de nouvelles pages et créer un menu de navigation qui sera affiché dans l’en-tête du site.

Configurer ce menu avec le paramètre nav dans le fichier mkdocs.yml :

site_name: My Docs
nav:
  - Accueil: index.md
  - Conférences:
    - Conférence PyLadiesCon: conferences/pyladiescon.md
    - Conférence PyConFR: conferences/pyconfr.md

Syntaxes Markdown

Note

One of the most confusing aspects of using Markdown is that practically every Markdown application implements a slightly different version of Markdown. ¹

MkDocs utilise la librairie Python-Markdown qui dispose de plusieurs extensions de syntaxe ²

• Syntaxe originelle de John Gruber (avec l’aide d’Aaron Swartz)
• initiative CommonMark : spécification adoptée par GitHub, GitLab, Stack Overflow, … et implémentée en Python par markdown-it-py
• RFC 776411 et RFC 776310
• Pandoc’s Mardown utilisé par Quarto
• MyST - Markdown for technical, scientific communication and publication - utilisé par Jupyter Book et Sphinx

Habituée à utiliser reStructuredText et Sphinx, je suis toujours un peu perplexe quand je dois utiliser des outils qui sont basés sur Markdown car les syntaxes varient.

• Syntaxe originelle créée en 2004
• CommonMark débutée en 2012, pallier le manque de standardisation et les ambiguïtés du format GitHub, GitLab, Stack Overflow, Swift, Discourse, Reddit, Qt
• 2 RFC en 2016

1. Voir dans la partie Flavors of Markdown du Markdown Guide

2. Voir Writing with Markdown

2 thèmes intégrés

1. thème par défaut : thème mkdocs
   basé sur Bootstrap

2. clone du thème par défaut du service
   Read the Docs

Déclaration du thème Read the Docs dans le fichier mkdocs.yml

site_name: My Docs

theme: readthedocs

Thème mkdocs :

• site adapatif
• modes de couleur : clair, sombre ou automatique
• composants bootstrap (avec HTML)

Thème Read the Docs:

• site adapatif

Traductions :

• responsive design : conception adaptative
• Définissez le mode de couleur par défaut du thème sur clair, sombre ou automatique.

Publication

Publication sur un serveur dédié

La commande mkdocs build génère les fichiers statiques à publier dans le dossier site :

$ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/.../my-site/site
INFO    -  Documentation built in 0.13 seconds

Copier les fichiers générés vers votre serveur dédié ¹ :

# Exemple de déploiement
$ scp -r ./site/* user@host:/path/to/my-mkdocs-site/

site
├── 404.html
├── conferences
│   ├── logo-pyconfr-2025.svg
│   ├── logo-pyladiescon.svg
│   ├── pyconfr
│   │   └── index.html
│   └── pyladiescon
│       └── index.html
├── css
│   ├── fonts
│   │   ├── fontawesome-webfont.eot
│   │   ├── fontawesome-webfont.svg
│   │   ├── …
│   │   └── Roboto-Slab-Regular.woff2
│   ├── theme.css
│   └── theme_extra.css
├── img
│   └── favicon.ico
├── index.html
├── js
│   ├── html5shiv.min.js
│   ├── jquery-3.6.0.min.js
│   ├── theme_extra.js
│   └── theme.js
├── search
│   ├── lunr.js
│   ├── main.js
│   ├── search_index.json
│   └── worker.js
├── search.html
├── sitemap.xml
└── sitemap.xml.gz

8 directories, 37 files

LE DISCOURS N’EST PAS TERRIBLE SUR CETTE DIAPO

1. Voir Deploying your docs - Other Providers

Publication sur Read the Docs

Read the Docs est la plateforme d’hébergement de référence des documentations Python.

• version communauté : gratuite pour les projets libres et les communautés
• hébergement de multiples versions de la documentation, en plusieurs langues
• plusieurs outils de documentation utilisables : MkDocs, Sphinx, Jupyter Book, …
• suivre le tutoriel Read the Docs

Quelques informations

Créée en 2010, le code de la plateforme est open source avec ~460 contributeurices.

Read the Docs héberge 80 000 projets open source, sert 55 millions de pages et 40 TB de documentation par mois. Il a 100 000 utilisateurs avec une équipe salariée de seulement 4 personnes.

Voir les comparaisons de Read the Docs avec d’autres plateformes : GitHub Pages, GitBook, Cloudflare Pages et Netlify

Suivre le tutoriel Read the Docs pour un guide pas à pas à partir d’un template de projet

Read the Docs : import de projet

Read the Docs recommande de s’authentifier à partir d’une plateforme d’hébergement de code (GitHub, GitLab, Bitbucket) pour faciliter l’import et la configuration des projets.

Read the Docs : fichier de configuration

Vous devez placer un fichier de configuration, nommé .readthedocs.yaml, à la racine de votre dépôt git pour configurer la génération de la documentation sur la plateforme.

# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details

# Required
version: 2

# Set the OS, Python version, and other tools you might need
build:
  os: ubuntu-24.04
  tools:
    python: "3.13"

# Build documentation with Mkdocs
mkdocs:
   configuration: mkdocs.yml

# Optionally, but recommended,
# declare the Python requirements required to build your documentation
# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
python:
   install:
   - requirements: docs/requirements.txt

# Fichier docs/requirements.txt

mkdocs

Read the Docs : tableau de bord

Une fois importée vous avez le tableau de bord suivant pour votre projet :

Voir si il faut détailler les étapes

~/Progs/python/mkdocs-uv/my-mkdocs-site-on-rtd.md

https://github.com/fconil/my-mkdocs-site-on-rtd https://my-mkdocs-site-on-rtd.readthedocs.io

Publication sur GitHub Pages

Déploiement sur GitHub Pages en tant que site “Project Pages”.

La commande mkdocs gh-deploy

1. génère le site
2. crée un commit sur la branche gh-pages, uniquement avec les fichiers générés
3. pousse le commit sur le remote (GitHub)
4. les pages sont mise en ligne : https://fconil.github.io/my-mkdocs-site-on-ghpages/

$ mkdocs gh-deploy
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/fconil/Progs/python/mkdocs-uv/my-mkdocs-site-on-ghpages/site
INFO    -  Documentation built in 0.11 seconds
INFO    -  Copying '/home/fconil/Progs/python/mkdocs-uv/my-mkdocs-site-on-ghpages/site' to 'gh-pages' branch and pushing to GitHub.
Énumération des objets: 52, fait.
Décompte des objets: 100% (52/52), fait.
Compression par delta en utilisant jusqu'à 4 fils d'exécution
Compression des objets: 100% (35/35), fait.
Écriture des objets: 100% (38/38), 802.00 Kio | 4.92 Mio/s, fait.
Total 38 (delta 7), réutilisés 0 (delta 0), réutilisés du pack 0
remote: Resolving deltas: 100% (7/7), completed with 3 local objects.
To github.com:fconil/my-mkdocs-site-on-ghpages.git
   c88cc7b..9104959  gh-pages -> gh-pages
INFO    -  Your documentation should shortly be available at: https://fconil.github.io/my-mkdocs-site-on-ghpages/

C’est très simple, quasiment magique avec mkdocs gh-deploy !

~/Progs/python/mkdocs-uv/my-mkdocs-site-on-ghpages.md

GitHub Pages : branches

Material for MkDocs

Présentation du thème Material for MkDocs

Material for MkDocs est construit sur MkDocs.

• le thème apporte un aspect moderne, adaptatif ¹, inspiré de Material Design ²

• excellent tutoriel de James Willett

• documentation claire

  • getting started
  • setup : comment structurer et changer l’apparence de votre site (palettes de couleurs, fontes, internationalisation, navigation, …), ainsi que les différentes extensions Markdown disponibles
  • plugins : les plugins indiqués par un COEUR sont réservés aux “sponsors”
  • reference détaille les éléments qui peuvent être utilisés les pages Markdown et la configuration nécessaire

Je vais vous présenter quelques options que j’ai utilisées pour mes pages personnelles.

C’est loin d’être exhaustif, car je n’ai utilisé qu’une petite partie des possibilités de Material for MkDocs, j’ai apprécié la facilité d’utilisation.

C’est grâce au thème Material for MkDocs, le plus populaire (présent dans la moitié des fichiers mkdocs.yml sur GitHub), que je me suis intéressée davantage à MkDocs.

Write your documentation in Markdown and create a professional static site in minutes – searchable, customizable, in 60+ languages, for all devices.

1. Voir Responsive Design

2. Voir les principes de Material Design 3

Mise en place aussi simple

1. Remplacer : pip install mkdocs par : pip install mkdocs-material

Installation

pip install mkdocs-material installe les dépendances nécessaires : MkDocs, Markdown, Pygments et Python Markdown Extensions : (une collection d’extensions de Python Markdown)

2. Changer la déclaration du thème et ajouter le paramètre site_url dans mkdocs.yml :

site_name: Mon site MkDocs sur GitHub Pages
site_url: https://fconil.github.io/my-mkdocs-site-on-ghpages/
nav:
  - Accueil: index.md
  - Conférences:
    - …
theme:
  name: material

site_url

Material for MkDocs recommande de définir site_url car MkDocs fait l’hypothèse que le site est hébergé à la racine du domaine. Certains plugins nécessitent que la propriété soit définie, donc il faut toujours la spécifier.

Apparence de base

Setup : Navigation

Quelques options de configuration de la navigation :

• navigation.tabs : afficher les titres de premier niveau dans le bandeau ¹
• toc.integrate : intégrer la table des matières à la barre de navigation de gauche
• navigation.instant : chargement instantané → les clics sur les liens internes sont interceptés et gérés via XHR ² pour éviter de recharger toute la page
• navigation.tracking : ajouter l’ancre courante du document à l’URL de la barre d’adresse
• navigation.top : affichage d’un bouton “back-to-top”

1. Navigation tabs pour les écrans >1220px

2. XMLHttpRequest

navigation.tabs et toc.integrate

theme:
  features:
    - navigation.tabs
    - toc.integrate

• afficher les titres de premier niveau dans le bandeau
• intégrer la table des matières à la navigation à gauche

Démonstration des 2 premières options : navigation.tabs et toc.integrate.

Ce sont des options visuellement présentables (XHR plus difficile sur des diapos).

Setup : Fontes

theme:
  font:
    text: Audiowide
    code: Source Code Pro

Possibilité de choisir parmi les 1000 fontes Google ou d’utiliser une fonte hébergée localement, voir Changing the fonts

Choose among 1,000 Google Fonts or load self-hosted fonts

Setup : Couleurs et mode

theme:
  palette:
    # Palette toggle for light mode (default)
    - scheme: default
      primary: light blue
      accent: pink
      toggle:
        icon: material/weather-night
        name: Dark mode

    # Palette toggle for dark mode (slate)
    - scheme: slate
      primary: teal
      accent: deep orange
      toggle:
        icon: material/weather-sunny
        name: Light mode

Voir Changing the colors

Exemple :

• changer la palette de couleurs avec les paramètres primary et accent
• afficher un bouton (configurable) pour passer du mode clair au mode sombre

Mode clair

Mode sombre

Setup : lien vers dépôt git

site_name: Mon site MkDocs sur GitHub Pages
site_url: https://fconil.github.io/my-mkdocs-site-on-ghpages/
repo_url: https://github.com/fconil/my-mkdocs-site-on-ghpages

Ajout d’un lien vers le dépôt git avec des informations (versions, stars, forks) dans le header :

Voir Adding a git repository

Setup : social link dans le footer

extra:
  # Social icons
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/fconil
    - icon: simple/mastodon
      link: https://framapiaf.org/@fcodvpt

Voir Setting up the footer - Social links

Intégrer des liens dans le footer sous forme d’icônes identifiée vers différentes plateformes :

Reference : Icons, Emojis

Material for MkDocs permet d’utiliser plus de 10 000 icônes et emojis.

Dans mkdocs.yml, déclarer :

1. attr_list (extension Python Mardown)
2. pymdownx.emoji (extension Python Mardown Extensions)

markdown_extensions:
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

Dans la page Markdown insérer le shortcode à afficher :

## Icônes et Emojis

- :simple-markdown: : documenter en Markdown
- :simple-materialformkdocs: : avec Material for MkDocs
- :mermaid: : utiliser Mermaid
- :simple-sphinx: : habituée à Sphinx

Rendu :

One of the best features of Material for MkDocs is the possibility to use more than 10,000 icons and thousands of emojis in your project documentation with practically zero additional effort. Moreover, custom icons can be added and used in mkdocs.yml, documents and templates.

Voir Icons and Emojis

Reference : Grids

Dans mkdocs.yml, déclarer 2 extensions Python Mardown :

markdown_extensions:
  - attr_list
  - md_in_html

Dans la page Markdown :

<div class="grid cards" markdown>

-   :material-clock-fast:{ .lg .middle } __Set up in 5 minutes__

    ---

    Install [`mkdocs-material`](#) with [`pip`](#) and get up
    and running in minutes
    
-   :fontawesome-brands-markdown:{ .lg .middle } __It's just Markdown__

    ---

    Focus on your content and generate a responsive and searchable static site

</div>  

Reference : Mermaid

Dans mkdocs.yml, déclarer l’extension Python Mardown Extensions suivante :

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

Dans la page Markdown, déclarer le diagramme Mermaid :

    ``` mermaid
    ---
    title: Déploiement MkDocs sur GitHub Pages
    ---
    gitGraph
       commit
       commit
       commit
       branch gh-pages
       commit
       switch main
       commit
       commit
       switch gh-pages
       commit
    ```

 

Conclusion

MkDocs et Material : un ensemble simple et efficace

1. Installez MkDocs et Material for MkDocs dans un environnement virtuel
2. Générez la structure du projet avec mkdocs new my-site
3. Ajoutez du contenu
4. Donnez une apparence moderne à votre site avec Material for MkDocs
5. Visualisez le rendu localement avec mkdocs serve
6. Publiez simplement votre documentation avec mkdocs build et mkdocs gh-deploy

Présentation en ligne : https://perso.liris.cnrs.fr/francoise.conil/creer-un-site-web-avec-mkdocs_pyladiescon-2025

Ce travail est sous licence CC BY-SA 4.0

Bande dessinée “Les décodeuses du numérique” / “The CodebreakHers of the digital world” de l’Institut CNRS Sciences Informatiquesa.

Annexes

Installation dans un environnement virtuel

Avec pip et venv

1. Création et activation du virtualenv

$ python3 -m venv .venv
$ source .venv/bin/activate
$ pip install --upgrade pip setuptools wheel

2. Installation de MkDocs

$ pip install mkdocs

Avec uv

1. Création et activation du virtualenv

$ uv venv
Using CPython 3.13.5
Creating virtual environment at: .venv
$ source .venv/bin/activate

2. Installation de MkDocs

$ uv pip install mkdocs

Important

La version de MkDocs qui sera installée par pip sera beaucoup plus récente que la version disponible dans vos paquets système.

navigation.tabs

theme:
  features:
    - navigation.tabs

Afficher les titres de premier niveau dans le bandeau

Voir : Setting up navigation - Navigation tabs pour les écrans >1220px