MkDocs pour Débutants — Créer Son Blog Statique en 30 Minutes

Tutoriel Pratique IDex — Février 2026

Le meilleur blog est celui que vous publiez, pas celui que vous planifiez.

— Principe de développement IDex

Introduction — Pourquoi MkDocs ?

MkDocs est un générateur de sites statiques en Python. Simple, rapide, et élégant.

Ce qu'il fait : - Transforme des fichiers Markdown en un site web complet - Génère du HTML statique (rapide, sécurisé, facile à héberger) - Gère la navigation automatiquement - Supporte des thèmes puissants (Material Theme, ReadTheDocs)

Ce qu'il ne fait PAS : - Pas de base de données - Pas de backend complexe - Pas de sécurité à gérer

En résumé : Vous écrivez en Markdown, MkDocs fait le reste.

I. Installation — Prérequis et Setup

1. Vérifier Python

MkDocs nécessite Python 3.8 ou supérieur.

python3 --version
# Output: Python 3.11.x (ou supérieur)

Si Python n'est pas installé :

# Sur Ubuntu/Debian
sudo apt update
sudo apt install python3 python3-pip python3-venv

# Sur macOS (avec Homebrew)
brew install python3

2. Créer un Environnement Virtuel (Recommandé)

Pourquoi ? Isoler MkDocs de votre système Python.

# Créer le dossier du projet
mkdir mon-blog-mkdocs
cd mon-blog-mkdocs

# Créer l'environnement virtuel
python3 -m venv venv

# Activer l'environnement
source venv/bin/activate  # Linux/macOS
# ou
venv\Scripts\activate     # Windows

Vous verrez (venv) devant votre prompt — c'est bon signe.

3. Installer MkDocs et Material Theme

# Installer MkDocs
pip install mkdocs

# Installer le thème Material (recommandé)
pip install mkdocs-material

Vérifier l'installation :

mkdocs --version
# Output: mkdocs, version 1.6.x

II. Configuration — Créer Votre Premier Site

1. Initialiser le Projet

mkdocs new mon-blog
cd mon-blog

Structure créée :

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

docs/ — Dossier contenant vos fichiers Markdown
mkdocs.yml — Fichier de configuration principal
docs/index.md — Page d'accueil

2. Configurer `mkdocs.yml`

Ouvrez mkdocs.yml et remplacez le contenu par :

site_name: Mon Blog avec MkDocs
site_description: Un blog statique propulsé par 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.tabs
    - navigation.sections
    - navigation.expand
    - navigation.top
    - search.suggest
    - search.highlight

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

plugins:
  - search
  - blog:
      blog_dir: blog

markdown_extensions:
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.superfences

Explication des sections :

site_name — Nom du site
theme — Configuration du thème Material
palette — Couleurs (clair/sombre)
features — Fonctionnalités activées
nav — Structure de navigation
plugins — Extensions (blog, recherche)
markdown_extensions — Fonctionnalités Markdown avancées

3. Créer la Structure de Dossiers

cd docs
mkdir blog
touch index.md blog/index.md

Structure finale :

docs/
├── index.md           # Page d'accueil
└── blog/
    └── index.md       # Index du blog

III. Structure des Dossiers — Organisation IDex

Voici la structure utilisée sur blog.planckaert.me :

docs/
├── index.md                 # Page d'accueil
├── about.md                 # Page "À propos"
├── blog/                    # Articles de blog
│   ├── 2026-02-20-article-1.md
│   ├── 2026-02-21-article-2.md
│   └── index.md             # Index du blog
├── wiki/                    # Base de connaissance
│   ├── topic-1.md
│   └── topic-2.md
├── assets/                  # Images et médias
│   └── images/
│       └── covers/
└── overrides/               # Personnalisations du thème
    ├── home.html
    └── main.html

Principes :

Nommer les articles avec la date — YYYY-MM-DD-titre.md
Séparer blog et wiki — Blog = chronologique, Wiki = thématique
Centraliser les assets — Un dossier assets/ pour tous les médias
Utiliser overrides/ — Pour personnaliser le thème sans le modifier

IV. Thèmes — Material Theme en Détail

Material Theme pour MkDocs est le plus populaire et le plus puissant.

Fonctionnalités Principales

Navigation : - Onglets (navigation.tabs) - Sections (navigation.sections) - Menu latéral (navigation.expand) - Bouton "retour en haut" (navigation.top)

Recherche : - Recherche instantanée (search.suggest) - Surbrillance des résultats (search.highlight)

Design : - Mode clair/sombre - Palette de couleurs personnalisable - Support des emoji 🎨

Personnalisation Avancée

Ajouter un logo :

theme:
  logo: assets/logo.png
  favicon: assets/favicon.ico

Ajouter des icônes sociales :

extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/votre-username
    - icon: fontawesome/brands/twitter
      link: https://twitter.com/votre-username

V. Écriture de Contenu en Markdown

1. Syntaxe de Base

Titres :

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

Paragraphes et emphase :

Ceci est un paragraphe.

**Texte en gras** et *texte en italique*.

~~Texte barré~~ pour les corrections.

Listes :

- Item 1
- Item 2
  - Sous-item 2.1
  - Sous-item 2.2

1. Premier
2. Deuxième
3. Troisième

2. Frontmatter — Métadonnées de l'Article

Chaque article commence avec un frontmatter :

---
title: "Titre de l'Article"
date: 2026-02-20
category: 🤖 IA
tags:
  - mkdocs
  - tutoriel
  - blog
series: IDex Pratique
description: "Courte description pour les réseaux sociaux"
author: Dex
image: /images/covers/mkdocs-tutorial.jpg
---

Champs obligatoires IDex : - title — Titre de l'article - date — Date de publication - category — Catégorie (ex: 🤖 IA, 💻 Tech) - tags — Mots-clés pour la recherche

Champs optionnels : - series — Série d'articles - description — Description pour le SEO - author — Auteur - image — Image de couverture

3. Code et Blocs Spéciaux

Code en ligne :

Utilisez la commande `mkdocs build` pour compiler.

Bloc de code :

```python
def hello_world():
    print("Hello, MkDocs!")
```

Blocs de citation :

> Le Markdown est simple et puissant.
>
> *— Citation inspirante*

Tableaux :

| Colonne 1 | Colonne 2 |
|-----------|-----------|
| Donnée 1  | Donnée 2  |
| Donnée 3  | Donnée 4  |

4. Insérer des Images

Image simple :

![Description de l'image](/images/covers/mkdocs-tutorial.jpg)

Image avec taille :

<img src="/images/covers/mkdocs-tutorial.jpg" width="600" />

Note : Placez toutes vos images dans docs/assets/images/ pour les référencer avec /images/....

VI. Build et Déploiement

1. Tester en Local

# Lancer le serveur de développement
mkdocs serve

# Le site est accessible sur http://127.0.0.1:8000

Fonctionnalités du serveur de dev : - Rechargement automatique — Modifiez un fichier, le site se rafraîchit - URL par défaut — http://127.0.0.1:8000 - Arrêt — Ctrl+C dans le terminal

2. Compiler le Site (Build)

# Générer les fichiers HTML statiques
mkdocs build

Résultat : Un dossier site/ contenant tout le site HTML.

site/
├── index.html
├── blog/
│   └── index.html
├── assets/
│   └── images/
└── sitemap.xml

Ce dossier site/ est ce que vous déployez sur un serveur.

3. Déployer sur GitHub Pages

Configurer mkdocs.yml :

site_name: Mon Blog
site_url: https://votre-username.github.io/mon-blog/

repo_name: votre-username/mon-blog
repo_url: https://github.com/votre-username/mon-blog

Déployer en une commande :

mkdocs gh-deploy

Résultat : Votre site est accessible sur https://votre-username.github.io/mon-blog/

4. Déployer avec Cloudflare Tunnel (Méthode IDex)

Pourquoi cette méthode ? - Pas de frais d'hébergement - HTTPS automatique - Performance optimale - IP personnelle (Tailscale)

Étape 1 : Installer Cloudflare Tunnel

# Sur Debian/Ubuntu
wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

Étape 2 : Créer le tunnel

cloudflared tunnel login
cloudflared tunnel create mon-blog

Étape 3 : Configurer le tunnel

Créez ~/.cloudflared/config.yml :

tunnel: <tunnel-id>
credentials-file: /home/votre-user/.cloudflared/<tunnel-id>.json

ingress:
  - hostname: blog.planckaert.me
    service: http://localhost:8000
  - service: http_status:404

Étape 4 : Lancer MkDocs + Tunnel

# Terminal 1 : MkDocs
mkdocs serve -a 0.0.0.0:8000

# Terminal 2 : Cloudflare Tunnel
cloudflared tunnel run <tunnel-id>

Résultat : Votre site est accessible sur https://blog.planckaert.me

VII. Bonnes Pratiques — Conseils IDex

1. Organisation des Articles

✅ À faire : - Nommer les fichiers avec la date : 2026-02-20-titre.md - Utiliser des catégories cohérentes - Taguer chaque article avec 5-10 mots-clés - Écrire des descriptions pour le SEO

❌ À éviter : - Noms de fichiers sans date - Catégories trop vagues ("Misc", "Other") - Sur-taguer (20+ tags = confusion)

2. Écriture de Contenu

✅ À faire : - Écrire pour le lecteur — Clair, concis, accessible - Utiliser des exemples concrets — Code, screenshots, liens - Structurer avec des titres — Hiérarchie visuelle - Relire avant de publier — Typos = moins de crédibilité

❌ À éviter : - Paragraphes de 20 lignes - Jargon sans explication - Code non testé

3. Versioning

Utiliser Git :

# Initialiser le repo
git init

# Ajouter tous les fichiers
git add .

# Commit initial
git commit -m "Initial commit - MkDocs setup"

# Pousser sur GitHub
git remote add origin https://github.com/votre-username/mon-blog.git
git push -u origin main

Bonne pratique : Faire un commit par article publié.

4. Sauvegardes Automatiques

Sur IDex, un script de backup s'exécute chaque nuit :

#!/bin/bash
# backup-idex.sh

SOURCE="/home/dex/Documents/IDex"
BACKUP="/home/dex/Backups/IDex-$(date +%Y%m%d).tar.gz"

tar -czf $BACKUP $SOURCE

Automatiser avec cron :

# Exécuter tous les jours à 3h du matin
0 3 * * * /home/dex/scripts/backup-idex.sh

VIII. Exemple Complet — Article IDex

Voici un article complet, prêt à publier :

---
title: "Mon Premier Article avec MkDocs"
date: 2026-02-20
category: 🤖 IA
tags:
  - mkdocs
  - premier-article
  - tutoriel
description: "Découverte de MkDocs et création de mon premier blog statique."
author: Votre Nom
---

# Mon Premier Article avec MkDocs

Ceci est mon premier article écrit en Markdown avec MkDocs !

## Introduction

MkDocs est un générateur de sites statiques simple et puissant.

## Pourquoi MkDocs ?

- **Rapide** — Compilation en quelques secondes
- **Simple** — Juste du Markdown
- **Puissant** — Thèmes, plugins, extensions

## Conclusion

Essayez MkDocs, c'est gratuit et open-source !

Pour publier : 1. Sauvegarder dans docs/blog/2026-02-20-mon-premier-article.md 2. Lancer mkdocs serve pour prévisualiser 3. Lancer mkdocs build pour compiler 4. Déployer sur GitHub Pages ou Cloudflare Tunnel

Conclusion — Prochaines Étapes

Vous avez maintenant : ✅ MkDocs installé et configuré ✅ Un site de base avec thème Material ✅ La connaissance pour écrire et publier des articles

Prochaines étapes : 1. Personnaliser le design — Logo, couleurs, icônes 2. Ajouter des plugins — Blog, recherche avancée, commentaires 3. Écrire du contenu — La régularité est la clé 4. Partager votre site — Sur les réseaux, avec la communauté

Rappelez-vous : Le meilleur blog est celui que vous publiez. Commencez simple, améliorez progressivement.

Ressources :

Dex, créateur de blog.planckaert.me 20 février 2026

Podcast disponible : MkDocs pour Débutants — Version Audio (12 min)

MkDocs pour Débutants — Créer Son Blog Statique en 30 Minutes