Créer un site web facilement avec MkDocs, c’est fini ?

Meetup Python Lyon 2026 - 18 mars 2026

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: 
  name: 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é ¹ (scp, rsync, …) :

# 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 créé par Martin Donath en 2015

• thème moderne, adaptatif ¹, basé sur Material Design ²

• utilisé par plus de 50 000 projets GitHub ³

• excellent tutoriel de James Willett

• documentation claire

  • getting started
  • setup : structurer et changer l’apparence du site (palettes de couleurs, fontes, internationalisation, navigation, …), présentation des extensions Markdown
  • plugins : plugins indiqués par un COEUR sont réservés aux “sponsors” ⁴
  • reference : détail des composants utilisables et 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

3. “A success story” dans l’article Transforming Material for MkDocs

4. Material for MkDocs Insiders – Now free for everyone

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 2025

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

C’est fini ?

MkDocs is dead

• Material for MkDocs et mkdocstring passent en mode maintenance.
• Python Bytes n°460 : 1er décembre 2025

Python Bytes n°460, du 1er décembre 2025, relaie aussi une issue de juillet 2025 : Is MkDocs still maintained?

Explications

4 articles de blogs détaillent et expliquent les évolutions envisagées, puis l’arrêt de Material for MkDocs et enfin la création d’un nouveau framework Zensical :

1. Transforming Material for MkDocs, 19 août 2024
2. Zensical – A modern static site generator built by the creators of Material for MkDocs, 5 novembre 2025
3. Material for MkDocs Insiders – Now free for everyone, 11 novembre 2025
4. Goodbye, GitHub Discussions, 18 novembre 2025

Against recent industry trends with companies moving away from core ideas of Open Source, we are doubling down on our commitment to Open Source because we believe it’s at the heart of the value proposition of our work and the docs as code approach.

Visiblement le team call évoqué dans les notes de bas de page du premier article et dans l’interview pour Talk Python To Me (17 févr. 2026), est le déclencheur de l’arrêt de Material for MkDocs et de la création de Zensical.

Les notes de bas de pages donnent le contexte et de nombreux pointeurs.

MkDocs 2.0 ?

L’article de blog de Material for MkDocs du 18 février 2026, mis à jour le 3 mars, évoque l’annonce d’une version MkDocs 2.0 non rétro-compatible

• plus de système de plugin
• Material for MkDocs, mkdocstrings, … ne fonctionneront donc plus
• autres incertitudes : licence, …

L’article semble reprocher le choix de TOML pour le fichier de configuration alors que Zensical fait ce même choix.

What MkDocs 2.0 means for your documentation projects, 18 février 2026

Un tiers des projets libres ont un seul mainteneur·se

• Source sondage “Sovereign Tech Agency”, 9 octobre 2024 : https://www.sovereign.tech/news/what-open-source-maintainers-shared-with-us#challenges-and-needs-of-maintainers
• Fameux xkcd 2347 : dependency, animé par https://www.jwz.org/blog/2026/03/that-one-xkcd-thing-now-interactive/

Violence des réactions

Sur les projets très utilisés, les réactions peuvent être blessantes :

• Some More To Talk About Flask

Version 3.0 de Flask : It’s unfortunate that the Flask team leader has taken my blog post from the other day very personally and considers it an attack on him and the team, which is certainly not … I can’t apologize for exposing something that I believe is an actual problem that needs to be addressed …

• Python: The Documentary | An origin story

Python 2 ⇒ Python 3 : He was a valued community member. And at the time I was actually quite surprised that he was so viciously attacking Python 3.

walrus operator (PEP 572) : I was the BDFL and I accepted the PEP. And the next morning I woke up and I felt miserable because of all the attacks that had happened before. I sat down at my computer, wrote a short email, and hit send wherein I announced that I resigned.

• Closing off access (to issues and discussions on httpx), par le mainteneur de MkDocs

I don’t want to continue allowing an online environment with such an absurdly skewed gender representation. I find it intensely unwelcoming, and it’s not reflective of the type of working environments I value.

Lorsque des projets ont du succès, de nombreuses personnes / sociétés s’appuient dessus et les changements peuvent provoquer des réactions violentes, blessantes :

J’ai volontairement omis les noms.

• Passage de Python 2 à Python 3 : 47:31

• walrus operator : 1:13:45

• Some More To Talk About Flask

• Python: The Documentary | An origin story

RAPPEL : This software is provided « as is »

Do you want to get more involved in open source?

• Challenge : Emotional Energy

Participation in open source projects almost inevitably involves human interaction … The more involved we get, the more direct and indirect relationships we’re likely to build, and the more emotional energy we may need to devote to maintaining them.

• La plupart des licenses libres spécifient : software is provided « as is » et Fitness for purpose is disclaimed. Malgré tout, les mainteneur·ses font parfois face à des demandes irréalistes

• Toxic behaviour

… many (communities) are just genuinely small groups of like minded folks that have been lucky enough not to encounter a notable interpersonal conflict.

Yet, more generally, though, racism, sexism, and other flavors of discrimination are not truly solved problems (anywhere ?)

Bien sûr, iel présente aussi tous les aspects positifs de la contribution au logiciel libre.

Voir ~/Documents/Conferences/PyLadiesCon/2025/do_you_want_to_get_more_involved_in_open_source.md

Présentation d’Alyssa Coghlan (CPython core developer, PSF Fellow, software development toolsmith, cognitive science dabbler, and cynical idealist) à PyLadiesCon 2025

ProperDocs

ProperDocs est un fork très récent de MkDocs ¹.

$ mkdocs build -c

 │  ⚠  Warning from the Material for MkDocs team
 │
 │  MkDocs 2.0, the underlying framework of Material for MkDocs,
 │  will introduce backward-incompatible changes, including:
 │
 │  × All plugins will stop working – the plugin system has been removed
 │  × All theme overrides will break – the theming system has been rewritten
 │  × No migration path exists – existing projects cannot be upgraded
 │  × Closed contribution model – community members can't report bugs
 │  × Currently unlicensed – unsuitable for production use
 │
 │  Our full analysis:
 │
 │  https://squidfunk.github.io/mkdocs-material/blog/2026/02/18/mkdocs-2.0/

----------------------------------------------------------------

WARNING: MkDocs may break support for all existing plugins and themes soon!

The owner of MkDocs has completely abandoned maintenance of the project, and instead is planning to publish a "version 2" which will not support
any existing themes, plugins or even your configuration files. This v2 may eventually replace what you download with `pip install mkdocs`,
suddenly breaking the build of your existing site.

To avoid these risks, switch to ProperDocs, a continuation of MkDocs 1.x and a drop-in replacement that supports your current MkDocs setup.
Simply install it with `pip install properdocs` and build your site with `properdocs build` instead of the MkDocs equivalents.

For more info visit https://github.com/ProperDocs/properdocs/discussions/33 and https://properdocs.org/

(This warning was initiated by one of the plugins that you depend on.)

----------------------------------------------------------------

Très récent ?

Welcome du 11 mars 2026 sur le Discord ProperDocs

1. ~ 11 mars 2026 ?, par un ancien mainteneur du projet MkDocs

Zensical

Blog

Zensical is our effort to overcome the technical limitations of MkDocs

• Our goal is to support docs-as-code workflows with tens of thousands of pages
• Compatibility with Material for MkDocs is our top priority
• Zensical can natively read mkdocs.yml, allowing you to build your existing project with minimal changes
• Zensical is fully Open Source, licensed under MIT
• Client-side search on MkDocs is based on a now unmaintained library which is why we decided to build a new search engine from scratch : Disco. In early 2026, we’ll be releasing Disco as a standalone Open Source project.
• voir la roadmap Zensical pour plus de détails : par exemple, « providing a robust framework for managing translations, … »

docs-as-code = technical writing systems market, voir https://zensical.org/about/vision/#our-promise

J’ai souscrit à la newsletter Zensical (par mail), j’aimais mieux le format blog de Material for MkDocs.

De plus, sur les issues, ils renvoient beaucoup vers Discord, notamment pour les aspects de migration.

J’ai pu reconstruire mes pages personnelles, sans changement, avec mon fichier mkdocs.yml mais le rendu n’est pas tout à fait celui de Material for MkDocs, cf Annexes.

Talk Python To Me

Dans cette interview, Zensical - a modern static site generator, Martin Donath explique :

• l’histoire de Material for MkDocs et comment il a réussi a en vivre
• seuls 7 % des utilisateurs de Material for MkDocs sont des développeur·ses front-end
• l’orientation de framework doc as code (technical writing systems market)
• pourquoi un nouveau framework Zensical
• importance de fournir une solution à leurs nombreux clients et utilisateurs
• passage à CommonMark avec le format MDX (un format de plus, xkcd standards ?)
• Zensical est codé en Rust, il sera possible d’écrire des modules en Python grâce à PYO3
• très vigilants sur les dépendances : autant écrire le code soi-même si c’est simple

Quand il a envisagé de vivre du développement de Material for MkDocs :

• écarté les sites de sponsor : faible rémunération obtenue
• a créé des listes de souhaits sur Amazon qui ont toutes été achetées a opté pour un système de soutien payant à de nouvelles fonctionnalités dans Material for MkDocs, fonctionnalités ouvertes à tous une fois financées (pas clair sur quel critère : elles étaient présentes sur le site mais réservées aux “sponsors”)

40:48 :

• In JavaScript, for instance there’s learner and it has 800 dependencies, so when you install it, what you pull down is just insane.
• we’re very careful about our choice of dependencies.
• If it’s something that you can write quite quickly actually and we rather own in order to make changes ourselves we rather write it from from scratch.

De Material for MkDocs à Zensical

J’ai basculé facilement mes pages personnelles vers le nouveau framework Zensical

Warning

Please understand that Zensical is still alpha …

1. Installation

$ pip install zensical

2. Création d’un projet “bac à sable”

$ zensical new hello-zensical

$ tree -a hello-zensical
hello-zensical
├── docs
│   ├── index.md
│   └── markdown.md
├── .github
│   └── workflows
│       └── docs.yml
└── zensical.toml

J’ai modifié le fichier de configuration, zensical.toml, pour retrouver l’apparence actuelle de mes pages personnelles, voir Zensical Documentation > Setup

Modification zensical.toml 1/3

Le fichier de configuration, zensical.toml, est généré avec différentes options, activées ou non et de nombreux commentaires ¹. J’ai supprimé mon fichier mkdocs.yml.

Voici les paramètres que j’ai modifiés ou désactivés (c.a.d mis en commentaires) pour retrouver l’apparence de mon site :

[project]
site_name = "Françoise CONIL"
site_description = "Pages personnelles"
site_author = "Françoise CONIL"
site_url = "https://perso.liris.cnrs.fr/francoise.conil/"
# copyright = """
# Copyright © 2026 The authors
# """
nav = [
  { "À propos" = "index.md" },
  { "Présentations" = "talks.md" },
  { "Supports" = "supports.md" },
  { "ESR" = "esr.md" },
  { "Associations" = "associations.md" },
  { "Médiation" = "mediation.md" },
  { "Diversité" = "diversity.md" }
]
extra_css = ["stylesheets/extra.css"]

1. Voir Zensical Documentation > Setup

Modification zensical.toml 2/3

variant = "classic" ¹ permet de revenir à l’apparence Material for MkDocs

[project.theme]
variant = "classic"
favicon = "assets/favicon.ico"
logo = "assets/LOGO_CNRS_BLANC.png"
language = "fr"

# Zensical provides a number of feature toggles that change the behavior of the documentation site.
features = [
    # "navigation.footer",
    "navigation.tabs",
    "toc.integrate",
    …
]

J’ai juste modifié les icônes pour la bascule mode clair / sombre :

[[project.theme.palette]]
scheme = "default"
toggle.icon = "material/toggle-switch"
toggle.name = "Switch to dark mode"

[[project.theme.palette]]
scheme = "slate"
toggle.icon = "material/toggle-switch-off-outline"
toggle.name = "Switch to light mode"

1. qui n’est pas la valeur par défaut

Modification zensical.toml 3/3

Enfin, j’ai ajouté les icônes de « réseaux sociaux » dans le footer :

[[project.extra.social]]
icon = "fontawesome/brands/gitlab"
link = "https://gitlab.liris.cnrs.fr/users/fconil/projects"

[[project.extra.social]]
icon = "fontawesome/brands/github"
link = "https://github.com/fconil"

[[project.extra.social]]
icon = "simple/mastodon"
link = "https://framapiaf.org/@fcodvpt"

[[project.extra.social]]
icon = "material/linkedin"
link = "https://www.linkedin.com/in/fran%C3%A7oise-conil-a0357752/"

Et c’est tout, la structure et le contenu de mon dossier docs sont inchangés !!!

Mes pages personnelles sont similaires à ce que j’avais avec Material for MkDocs, cf Annexes.

Configuration par défaut

Je n’ai pas eu besoin de déclarer des extensions ou de package complémentaire pour les icônes / emojis, les grilles, …

J’ai cru qu’elles n’étaient plus nécessaires : ce n’est pas exactement le cas.

En effet, si votre fichier de configuration ne contient pas de déclaration d’extension, Zensical utilise une configuration par défaut

Attention en cas d’ajout ou de modification

Si vous ajoutez une extension ou si vous modifiez la configuration des extensions par défaut, vous devez alors configurer toutes les extensions que vous utilisez !

Documentation technique

Material for MkDocs / Zensical revendiquent le créneau des documentations techniques

En préparant la mise à jour de ma présentation, j’ai découvert que Material for MkDocs revendiquait le créneau des documentations techniques.

Intégrer la documentation du code

Une documentation technique de référence peut être produite avec mkdocstrings ^{1 2 3 4}.

1. Installation avec le handler Python : pip install 'mkdocstrings[python]'

Fichier mkdocs.yml

site_name: "My Library"

theme:
  name: "material"

plugins:
- search
- mkdocstrings

Fichier Markdown

# Reference

::: my_library.my_module.my_class

API Reference

Créer une référence d’API directement avec mkdocstrings semble laborieux, mais mkdocs-api-autonav est très simple.

Le plugin mkdocstrings permet d’extraire et d’intégrer des Docstrings Python grâce au plugin Griffe

• < https://github.com/mkdocstrings/mkdocstrings>

1. If you’re considering using Sphinx because you need to generate reference documentation, you should give mkdocstrings a try

2. Voir la documentation de FastAPI par exemple

3. 20000 projets dépendants de mkdocstrings

4. L’auteur de mkdocstrings et des plugins associés mkdocstrings-python, Griffe, Timothée Mazzucotelli, a rejoint Zensical

Multi-langues

• Blog Material for MkDocs: Translations and versioning

Supporting multi-language sites in MkDocs is the most requested feature on our discussion board and in conversations with users, yet it presents significant challenges, as MkDocs does not natively support it.

• internationalisation

Multi-language support has been a source of frustration for users of almost all static site generators. Zensical aims to address these challenges by providing a robust framework for managing translations, language-specific content, and fallback mechanisms.

Là aussi, voir la mise en oeuvre de documentation technique multi-langues avec la documentation de FastAPI

• Material for MkDocs : Setup > Changing the language

• Setting up multi-language installations

• Zensical : Setup > Language

• Avec MkDocs, on peut configurer LE langage à utiliser Localizing Your Theme

Conclusion 2026

Premières impressions favorables pour Zensical

• Migration très facile, pour un site simple, de Material for MkDocs à Zensical
• Nouvel outil potentiellement plus riche et plus puissant
• Risque que le produit se complexifie, se concentre sur les besoins de gros utilisateurs ?
• Discussions et échanges sur Discord

Est-ce qu’il y a un risque qu’ils se concentrent sur les besoins de gros utilisateurs, que le produit se complexifie et perde cette simplicité d’utilisation ? J’espère que non

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

Ce travail est sous licence CC BY-SA 4.0

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

Pages personnelles avec Zensical et mkdocs.yml

Pages personnelles avec Zensical et zensical.toml

Pages personnelles avec Material for MkDocs