MkDocs, Material et Zensical

Conférences éclair April 2026 - 28 mars 2026

Françoise CONIL, Administratrice April, Ingénieure CNRS au laboratoire LIRIS Lyon

MkDocs

MkDocs : générateur de sites statiques

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

  • 91 000 projets sur GitHub 2
  • orienté documentation technique
  • sources Markdown
  • documentation claire
  • serveur web intégré
  • greffon de recherche (lunr.js)

Installation :

pip install mkdocs

Structure générée très légère

  1. mkdocs new my-site
  2. cd my-site
  3. mkdocs serve

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.

2 thèmes intégrés

  1. Thème mkdocs par défaut

    • site adapatif
    • modes clair / sombre / automatique
    • composants Bootstrap

  2. Thème Read the Docs

Déclaration du thème dans mkdocs.yml

site_name: My Docs

theme: 
  name: readthedocs

Publication aisée

Serveur dédié

  1. mkdocs build génère les fichiers statiques dans le dossier site (par défaut)
  2. Copier les fichiers générés vers votre serveur dédié (scp, rsync, …)

GitHub 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
...
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/

Material for MkDocs

Thème MkDocs le plus populaire

Material for MkDocs créé par Martin Donath en 2015

Mise en oeuvre triviale

  1. pip install mkdocs-material
  2. Changer la déclaration du thème
site_name: Mon site MkDocs sur GitHub Pages
site_url: https://fconil.github.io/my-mkdocs-site-on-ghpages/
nav:
  - Accueil: index.md

theme:
  name: material

Facilités d’adaptation de l’apparence

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

 

Mode clair

Mode sombre

Décembre 2025 : c’est fini ?

MkDocs is dead

4 articles de blogs expliquent :

  1. les évolutions envisagées et les limitations de MkDocs
  2. l’arrêt de Material for MkDocs
  3. la création d’un nouveau framework Zensical :

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.

The Slow Collapse of MkDocs

Les turbulences du projet MkDocs ont été recensées dans cet article du 22 mars 2026 : https://fpgmaas.com/blog/collapse-of-mkdocs/

The MkDocs ecosystem is fragmenting in real time. Three successors, three visions, and a community deciding which bet to place.


MkDocs 2.0 ?

Un article de blog de Material for MkDocs du 18 février 2026, évoque l’annonce d’une version MkDocs 2.0 par son/sa créateurice.

Cette version sera non rétro-compatible :

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

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, … »

De Material for MkDocs à Zensical

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

  1. pip install zensical

Warning

Please understand that Zensical is still alpha …

Le fichier de configuration, zensical.toml, est généré avec différentes options, activées ou non et de nombreux commentaires 1.

J’ai supprimé mon fichier mkdocs.yml.

La structure et le contenu de mon dossier docs sont inchangés !!!

Je n’ai pas eu besoin de déclarer des extensions ou de package complémentaire pour les icônes / emojis, les grilles, … En effet, si votre fichier de configuration ne contient pas de déclaration d’extension, Zensical utilise une configuration par défaut

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

Difficultés de maintenir un projet libre

Un tiers des projets libres ont un seul mainteneur·se

Violence des réactions

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

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 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.

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.

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.

60 % des mainteneur·ses non payés

60 % des mainteneur·ses ont ou pensent abandonner

Slopocalypse - AI slop pull requests

jazzband is sunsetting

Note

Over 10 years ago, Jazzband started as a cooperative experiment to reduce the stress of maintaining Open Source software projects.

The idea was simple – everyone who joins gets access to push code, triage issues, merge pull requests. “We are all part of this.”

GitHub’s slopocalypse 1 – the flood of AI-generated spam PRs and issues – has made Jazzband’s model of open membership and shared push access untenable.

Jazzband was designed for a world where the worst case was someone accidentally merging the wrong PR.

In a world where :

an organization that gives push access to everyone who joins simply can’t operate safely anymore.

Destruction de modèles de revenus et des communautés

Open Source After the Extraction

Julien Danjou : https://julien.danjou.info/blog/open-source-after-the-extraction/

L’ancien deal de l’open source est mort : l’IA extrait le code sans nourrir la communauté. Les mainteneurs voient les téléchargements exploser mais les contributions disparaître.

Tailwind CSS

Tailwind CSS licencie 75% de son équipe technique à cause de l’IA

Le traffic sur leur documentation où se trouve leurs offres de support a chuté de 40 %.

Réécriture de logiciels avec l’IA en une semaine

chardet

autres cas