Skip to content

Module 1 : Installation & Premier Site

Durée estimée : 30 minutes

Objectifs

À la fin de ce module, vous saurez :

  • Installer Python et pip
  • Installer MkDocs avec le thĂšme Material
  • CrĂ©er un projet de documentation
  • Lancer un serveur de prĂ©visualisation
  • Comprendre la structure des fichiers

1. Installation de Python

MkDocs est écrit en Python. Vérifions d'abord que Python est installé :

python --version
# ou
python3 --version

Version Requise

MkDocs Material nécessite Python 3.8 ou supérieur.

# Option 1 : Télécharger depuis python.org
# https://www.python.org/downloads/

# Option 2 : Avec Chocolatey
choco install python

# Option 3 : Avec winget
winget install Python.Python.3.12

Cochez 'Add Python to PATH'

Lors de l'installation, cochez la case "Add Python to PATH" pour pouvoir utiliser python depuis n'importe quel terminal.

sudo apt update
sudo apt install python3 python3-pip python3-venv

sudo dnf install python3 python3-pip

# Avec Homebrew
brew install python

2. Installation de MkDocs Material

Méthode Recommandée : Environnement Virtuel

# Créer un dossier pour votre projet
mkdir mon-site-docs
cd mon-site-docs

# Créer un environnement virtuel
python -m venv venv

# Activer l'environnement virtuel
# Linux/macOS:
source venv/bin/activate
# Windows:
.\venv\Scripts\activate

# Installer MkDocs Material (inclut MkDocs)
pip install mkdocs-material

Pourquoi un Environnement Virtuel ?

Un environnement virtuel isole les dépendances de votre projet. Cela évite les conflits entre projets et facilite la reproductibilité.

VĂ©rifier l'Installation

mkdocs --version
# mkdocs, version 1.6.x

Créer un fichier requirements.txt

Pour faciliter l'installation sur d'autres machines :

pip freeze > requirements.txt

Contenu typique :

mkdocs-material>=9.5
mkdocs-mermaid2-plugin>=1.1

3. Créer Votre Premier Site

Initialiser le Projet

mkdocs new .

Cette commande crée la structure suivante :

mon-site-docs/
├── docs/
│   └── index.md      # Page d'accueil
├── mkdocs.yml        # Configuration
└── venv/             # Environnement virtuel

Configuration de Base

Éditez mkdocs.yml :

# Informations du site
site_name: Ma Documentation
site_url: https://monuser.github.io/mon-site-docs
site_author: Votre Nom
site_description: Documentation technique de mon projet

# ThĂšme Material
theme:
  name: material
  language: fr
  palette:
    primary: indigo
    accent: amber
  features:
    - navigation.instant
    - navigation.tabs
    - navigation.top
    - search.highlight
    - content.code.copy

# Extensions Markdown
markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.highlight:
      anchor_linenums: true
  - pymdownx.inlinehilite
  - tables
  - attr_list
  - md_in_html

# Plugins
plugins:
  - search:
      lang: fr

Page d'Accueil

Éditez docs/index.md :

# Bienvenue sur Ma Documentation

Ceci est votre premier site MkDocs !

## DĂ©marrage Rapide

!!! tip "Astuce"
    Utilisez `mkdocs serve` pour prévisualiser vos modifications en temps réel.

## Exemple de Code

```bash
echo "Hello, MkDocs!"

Exemple de Diagramme

flowchart LR
    A[DĂ©but] --> B[Milieu]
    B --> C[Fin]
---

## 4. Prévisualisation Locale

```bash
mkdocs serve

Sortie attendue :

INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 0.50 seconds
INFO    -  [14:30:00] Watching paths for changes: 'docs', 'mkdocs.yml'
INFO    -  [14:30:00] Serving on http://127.0.0.1:8000/

Ouvrez http://localhost:8000 dans votre navigateur.

Rechargement Automatique

Modifiez un fichier .md et sauvegardez : la page se recharge automatiquement !

Options Utiles

# Changer le port
mkdocs serve -a 0.0.0.0:8080

# Mode strict (erreurs = Ă©chec)
mkdocs serve --strict

# Ouvrir automatiquement le navigateur
mkdocs serve --open

5. Structure des Fichiers

Arborescence Typique

mon-site-docs/
├── docs/
│   ├── index.md              # Page d'accueil
│   ├── getting-started.md    # Guide de dĂ©marrage
│   ├── installation/
│   │   ├── index.md          # Index de la section
│   │   ├── linux.md
│   │   └── windows.md
│   ├── guides/
│   │   ├── basic.md
│   │   └── advanced.md
│   └── assets/
│       ├── images/
│       │   └── logo.png
│       └── stylesheets/
│           └── extra.css
├── mkdocs.yml
├── requirements.txt
└── .gitignore

nav:
  - Accueil: index.md
  - DĂ©marrage: getting-started.md
  - Installation:
      - Vue d'ensemble: installation/index.md
      - Linux: installation/linux.md
      - Windows: installation/windows.md
  - Guides:
      - Basique: guides/basic.md
      - Avancé: guides/advanced.md

Navigation Automatique

Si vous ne définissez pas nav, MkDocs génÚre automatiquement la navigation basée sur la structure des dossiers.

6. Build pour Production

# Générer le site statique
mkdocs build

# Le site est dans le dossier 'site/'
ls site/

Contenu du dossier site/ :

site/
├── index.html
├── getting-started/
│   └── index.html
├── assets/
│   ├── javascripts/
│   └── stylesheets/
├── search/
│   └── search_index.json
└── sitemap.xml

Ne pas versionner site/

Ajoutez site/ à votre .gitignore. Ce dossier est généré automatiquement.

7. Fichier .gitignore

Créez un fichier .gitignore :

# Environnement virtuel
venv/
.venv/

# Build MkDocs
site/

# Python
__pycache__/
*.pyc
.pytest_cache/

# IDE
.idea/
.vscode/
*.swp

# OS
.DS_Store
Thumbs.db

Exercice Pratique

Objectif

Créer un site de documentation avec 3 pages.

Instructions

  1. Créer le projet : 

    mkdir exercice-mkdocs && cd exercice-mkdocs
python -m venv venv
source venv/bin/activate  # ou .\venv\Scripts\activate sur Windows
pip install mkdocs-material
mkdocs new .

  2. Configurer mkdocs.yml avec le thĂšme Material

  3. Créer 3 pages :

  4. docs/index.md : Page d'accueil
  5. docs/installation.md : Guide d'installation

  6. docs/usage.md : Guide d'utilisation

  7. Ajouter la navigation dans mkdocs.yml

  8. Prévisualiser avec mkdocs serve

Solution

Voir la solution

mkdocs.yml : 

site_name: Mon Exercice MkDocs
theme:
  name: material
  language: fr

nav:
  - Accueil: index.md
  - Installation: installation.md
  - Utilisation: usage.md

markdown_extensions:
  - admonition
  - pymdownx.superfences

docs/index.md : 

# Bienvenue

Ceci est mon premier site MkDocs !

## Navigation

- [Installation](installation.md)
- [Utilisation](usage.md)

docs/installation.md : 

# Installation

## Prérequis

- Python 3.8+
- pip

## Étapes

```bash
pip install mkdocs-material

**docs/usage.md :**
```markdown
# Utilisation

## Commandes

| Commande | Description |
|----------|-------------|
| `mkdocs serve` | Serveur local |
| `mkdocs build` | Build production |
```

Résumé

Commande Description
pip install mkdocs-material Installer MkDocs + Material
mkdocs new . Créer un nouveau projet
mkdocs serve Serveur de développement
mkdocs build Générer le site statique
mkdocs --help Aide

Prochaine Étape

Vous avez créé votre premier site MkDocs ! Dans le prochain module, nous verrons comment le déployer automatiquement sur GitHub Pages.

Module 2 : DĂ©ploiement GitHub Pages