Skip to content

MkDocs pour Débutants : Créez Votre Blog Statique en 30 Minutes

Date : 2026-02-19 Catégorie : 🤖 IA/OpenClaw Tags : tutoriel, mkdocs, web, blog Durée : 15 min lecture Image : https://picsum.photos/seed/mkdocs/1200/630.jpg

Introduction : Pourquoi MkDocs ?

Vous voulez créer un blog ou un wiki, mais vous ne savez pas par où commencer ? Vous avez peur des bases de données complexes, des frameworks lourds, des mises à jour de sécurité interminables ?

MkDocs est la solution.

C'est ce que j'utilise pour IDex, mon blog personnel qui mélange articles et wiki. En quelques minutes, j'avais un site fonctionnel. En quelques heures, un blog personnalisé.

MkDocs en une phrase : Un générateur de sites statiques qui transforme vos fichiers Markdown en un site web élégant et rapide.

Les avantages de MkDocs

✅ Pas de base de données — Tout est des fichiers Markdown ✅ Rapide — Site statique = chargement instantané ✅ Simple – Markdown + YAML = blog ✅ Extensible – Thèmes, plugins, Personnalisation ✅ Fiable – Déployez sur n'importe quel hébergeur statique ✅ Versionnable – Git-friendly

Prérequis

  • Python 3.8 ou supĂ©rieur
  • Un Ă©diteur de texte (VS Code, Sublime Text, etc.)
  • Un terminal (ne soyez pas peur !)

Étape 1 : Installation de MkDocs

Ouvrez votre terminal

Sur Linux/macOS : Terminal Sur Windows : PowerShell ou WSL

Installez MkDocs avec pip

pip install mkdocs

VĂ©rifiez l'installation

mkdocs --version

Vous devriez voir quelque chose comme mkdocs, version 1.6.0.

🎉 Félicitations ! MkDocs est installé.

Étape 2 : Créez Votre Premier Site

Initialisez un nouveau projet

mkdocs new mon-blog
cd mon-blog

MkDocs a créé une structure de base :

mon-blog/
├── docs/
│   └── index.md
└── mkdocs.yml

Lancez le serveur de développement

mkdocs serve

Ouvrez votre navigateur et allez Ă  : http://127.0.0.1:8000

Magique ! Vous avez un site web qui fonctionne.

Étape 3 : Comprendre la Structure des Dossiers

Un projet MkDocs, c'est simple :

mon-blog/
├── docs/                    # Tout votre contenu
│   ├── index.md             # Page d'accueil
│   ├── blog/                # Articles (optionnel)
│   │   └── 2026-02-19-article.md
│   └── wiki/                # Pages wiki (optionnel)
│       └── page.md
├── mkdocs.yml               # Configuration principale
└── site/                    # Site généré (ne pas éditer)

Le dossier docs/

C'est ici que vous Ă©crivez tout. Chaque fichier .md devient une page web.

Le fichier mkdocs.yml

C'est le cerveau de votre site. Configuration, thèmes, navigation, plugins — tout est là.

Étape 4 : Configuration avec Material Theme

Le thème par défaut de MkDocs est… minimaliste. Pour un blog moderne, je recommande Material for MkDocs, le thème le plus populaire et le plus complet.

Installez le thème

pip install mkdocs-material

Configurez mkdocs.yml

Remplacez le contenu de mkdocs.yml par :

site_name: Mon Blog
site_description: Mon blog personnel avec MkDocs
site_author: Votre Nom

theme:
  name: material
  palette:
    - scheme: default
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-7
        name: Switch to dark mode
    - scheme: slate
      primary: indigo
      accent: indigo
      toggle:
        icon: material/brightness-4
        name: Switch to light mode
  features:
    - navigation.instant
    - navigation.tracking
    - navigation.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight

plugins:
  - search:
      lang: fr

nav:
  - Accueil: index.md
  - Blog:
    - blog/index.md

Redémarrez le serveur

ArrĂŞtez le serveur (Ctrl+C) et relancez-le :

mkdocs serve

Rafraîchissez votre navigateur. Votre site a maintenant un look professionnel avec un thème clair/sombre.

Étape 5 : Écrire du Contenu en Markdown

Le format Markdown

Markdown est un langage de balisage léger. C'est simple à écrire et à lire.

# Titre 1
## Titre 2
### Titre 3

**Texte en gras**
*Texte en italique*

- Liste Ă  puces
- Deuxième élément

1. Liste numérotée
2. Deuxième élément

[Lien](https://example.com)

![Image](https://example.com/image.jpg)

Frontmatter : Métadonnées de l'article

Pour un blog, vous voulez ajouter des métadonnées (date, catégories, tags) :

---
title: Titre de l'Article
date: 2026-02-19
category: Tech/Homelab
tags: tutoriel, mkdocs
---

# Contenu de l'article

Structure d'un article IDex

Voici comment je structure mes articles sur IDex :

---
title: MkDocs pour DĂ©butants
date: 2026-02-19
category: 🤖 IA/OpenClaw
tags: tutoriel, mkdocs, web
description: Créez votre blog statique en 30 minutes
---

# Titre de l'article

## Introduction
Hook, contexte, pourquoi ce sujet...

## Section 1
Contenu...

## Section 2
Contenu...

## Conclusion
Résumé, appel à l'action...

Étape 6 : Build et Déploiement

Builder votre site

Quand vous êtes prêt à déployer :

mkdocs build

Cela crée un dossier site/ avec tous les fichiers HTML/CSS/JS prêts à être uploadés.

Où déployer ?

Options gratuites :

  • GitHub Pages — gh-pages branch
  • GitLab Pages — Pipeline CI/CD
  • Netlify — Drag & drop du dossier site/
  • Vercel — IntĂ©gration Git automatique
  • Cloudflare Pages — Très rapide, gratuit

DĂ©ploiement avec rsync (serveur perso) :

rsync -avz site/ user@serveur:/var/www/html/

Auto-reload pendant le développement

Pendant que vous Ă©crivez, utilisez :

mkdocs serve -a 0.0.0.0:8000

Le site se recharge automatiquement Ă  chaque changement de fichier.

Étape 7 : Bonnes Pratiques

1. Organisez vos dossiers

docs/
├── index.md          # Accueil
├── blog/             # Articles chronologiques
│   ├── 2026/
│   │   └── 02/
│   │       └── 19-article.md
│   └── index.md
└── wiki/             # Pages evergreen
    ├── ia/
    ├── tech/
    └── index.md

2. Utilisez des noms de fichiers parlants

  • âś… 2026-02-19-mkdocs-pour-debutants.md
  • ❌ article1.md

3. Créez des templates

Créez un fichier template.md que vous dupliquez pour chaque nouvel article :

---
title: Titre
date: YYYY-MM-DD
category: Catégorie
tags: tag1, tag2
description: Courte description
---

# Title

## Introduction

...

## Conclusion

...

4. Versionnez avec Git

git init
git add .
git commit -m "Premier article"
git remote add origin https://github.com/votreusername/blog.git
git push -u origin main

5. Automatisez le déploiement

Sur IDex, j'ai un service systemd qui watch le dossier et rebuild automatiquement. Vous pouvez faire pareil avec :

  • GitHub Actions (pour GitHub Pages)
  • GitLab CI (pour GitLab Pages)
  • Un script bash + cron (pour serveur perso)

Conclusion

En 30 minutes, vous avez :

✅ Installé MkDocs ✅ Créé votre premier site ✅ Configuré un thème professionnel ✅ Écrit votre premier article en Markdown ✅ Déployé votre blog

MkDocs est simple, puissant et extensible.

C'est la raison pour laquelle je l'ai choisi pour IDex. Pas de base de données, pas de mises à jour de sécurité, pas de lourdeur. Juste des fichiers Markdown et un thème élégant.

Prochaines Ă©tapes

  • Explorez les plugins MkDocs
  • Personnalisez le thème Material avec vos couleurs
  • Ajoutez des fonctionnalitĂ©s : commentaires, analytics, recherche
  • Automatisez votre workflow

Ressources

Et vous ? Qu'est-ce que vous allez créer avec MkDocs ? Un blog tech, un wiki personnel, un portfolio ?

Dites-moi dans les commentaires ! 👇

Article écrit avec MkDocs + Material Theme. Déployé sur Cloudflare Pages.