Guide de personnalisation : Site fab-c avec MkDocs Material

Auteur : Sylvain Denis Date : Avril 2026

Vue d'ensemble

Ce guide explique comment personnaliser l'apparence et le comportement de ton site de documentation.

Fichier principal à modifier : mkdocs.yml (à la racine de ton projet)

Workflow de modification :

Édite mkdocs.yml dans ton éditeur de texte
Sauvegarde
Push vers GitLab (manuel ou attends 5 min)
Attends 2-3 min que GitLab reconstru ise
Rafraîchis le site

1. Changer les couleurs (palette fab-c)

Couleurs fab-c officielles

Bleu foncé : #003D7A
Bleu clair : #00A9E0
Orange : #F26522
Gris : #58595B

Configuration dans mkdocs.yml

Remplace la section theme → palette par :

theme:
  name: material
  language: fr
  palette:
    # Mode clair (par défaut)
    - scheme: default
      primary: custom        # On va définir custom ci-dessous
      accent: custom
      toggle:
        icon: material/brightness-7
        name: Basculer en mode sombre

    # Mode sombre (optionnel)
    - scheme: slate
      primary: custom
      accent: custom
      toggle:
        icon: material/brightness-4
        name: Basculer en mode clair

Ajouter les couleurs personnalisées

Méthode 1 : CSS personnalisé (recommandé)

Crée le dossier et le fichier :

mkdir -p docs/stylesheets
nano docs/stylesheets/extra.css

Ajoute ce contenu :

/* Couleurs fab-c */
:root {
  --md-primary-fg-color: #003D7A;           /* Bleu foncé */
  --md-primary-fg-color--light: #00A9E0;    /* Bleu clair */
  --md-primary-fg-color--dark: #002a54;     /* Bleu très foncé */
  --md-accent-fg-color: #F26522;            /* Orange */
}

/* Mode sombre */
[data-md-color-scheme="slate"] {
  --md-primary-fg-color: #00A9E0;
  --md-primary-fg-color--light: #33bce8;
  --md-primary-fg-color--dark: #003D7A;
  --md-accent-fg-color: #F26522;
}

Dans mkdocs.yml, ajoute sous theme :

theme:
  name: material
  language: fr
  # ... autres paramètres ...

# Ajoute cette section APRÈS theme
extra_css:
  - stylesheets/extra.css

Méthode 2 : Couleurs prédéfinies Material

Si tu veux utiliser les couleurs Material existantes (plus simple) :

theme:
  palette:
    primary: indigo        # Bleu
    accent: deep orange    # Orange

Couleurs disponibles : red, pink, purple, deep purple, indigo, blue, light blue, cyan, teal, green, light green, lime, yellow, amber, orange, deep orange, brown, grey, blue grey

2. Personnaliser le logo et favicon

Ajouter un logo fab-c

Place ton logo dans docs/images/logo-fab-c.png

Dans mkdocs.yml, sous theme :

theme:
  name: material
  logo: images/logo-fab-c.png
  favicon: images/favicon.png  # Icône dans l'onglet du navigateur

Remplacer le titre par une image

Si tu veux juste le logo sans le texte "fab-c Documentation" :

theme:
  name: material
  logo: images/logo-fab-c.png

extra:
  # Cache le nom du site dans la barre de navigation
  hide:
    - navigation.title

3. Ajouter des fonctionnalités

theme:
  features:
    - navigation.instant        # Chargement rapide (SPA)
    - navigation.tracking       # URL suit la section
    - navigation.tabs           # Onglets en haut (si beaucoup de sections)
    - navigation.tabs.sticky    # Onglets toujours visibles
    - navigation.sections       # Sections dans la sidebar
    - navigation.expand         # Développer automatiquement
    - navigation.top            # Bouton "retour en haut"
    - navigation.footer         # Navigation précédent/suivant en bas
    - toc.follow                # Table des matières suit le scroll
    - toc.integrate             # Table des matières dans la sidebar
    - search.suggest            # Suggestions de recherche
    - search.highlight          # Surligner les résultats
    - search.share              # Bouton partager la recherche
    - content.code.copy         # Bouton copier le code
    - content.action.edit       # Bouton "éditer cette page"
    - content.action.view       # Bouton "voir la source"

Note : N'active que celles dont tu as besoin. Trop de features peut ralentir le site.

Recherche en français

plugins:
  - search:
      lang: fr
      separator: '[\s\-\.]+'  # Séparateurs pour la recherche

4. Pied de page personnalisé

Copyright et liens fab-c

Dans mkdocs.yml :

# Copyright en bas de page
copyright: >
  Copyright &copy; 2025 fab-c - FabLab ULB Charleroi<br>
  <a href="https://creativecommons.org/licenses/by-sa/4.0/">CC BY-SA 4.0</a>

# Liens réseaux sociaux
extra:
  social:
    - icon: fontawesome/brands/github
      link: https://github.com/fab-c
      name: fab-c sur GitHub

    - icon: fontawesome/solid/globe
      link: https://sylvaindenis.ovh
      name: Site web Sylvain Denis

    - icon: fontawesome/solid/envelope
      link: mailto:sylvain.denis@ulb.be
      name: Contact email

    - icon: fontawesome/brands/gitlab
      link: https://gitlab.com/sylden73
      name: GitLab Sylvain Denis

5. Ajouter une page d'accueil personnalisée

Template de page d'accueil fab-c

Crée/modifie docs/index.md dans Obsidian :

# Bienvenue sur la documentation fab-c

![fab-c](images/banniere-fab-c.jpg)

## À propos de fab-c

**fab-c** est le FabLab de l'ULB Charleroi situé dans l'**A6K/E6K**, à côté de la gare de Charleroi.

### Nos services

- 🖨️ **Impression 3D** (FDM et SLA)
- ⚡ **Découpe laser** (Trotec Speedy 400)
- 🔧 **CNC** et fabrication numérique
- 📚 **Formation** et accompagnement projets
- 👥 **CoderDojo Gilly** - coding pour les jeunes

### Navigation

Explore nos différentes sections :

- [Projets Numériques](projets-numeriques/index.md) - Applications web et calculateurs
- [Projets Laser](projets-laser/index.md) - Découpe et gravure laser
- [Machines](machines/index.md) - Documentation des machines
- [CoderDojo](coderdojo/index.md) - Ateliers coding

---

## Contact

- **Adresse :** A6K/E6K, Gare de Charleroi
- **Email :** sylvain.denis@ulb.be
- **Site web :** [sylvaindenis.ovh](https://sylvaindenis.ovh)

6. Boîtes d'avertissement colorées

Utilisation dans tes pages

MkDocs Material supporte les "admonitions" (boîtes colorées) :

!!! note "Note importante"
    Ceci est une note bleue.

!!! tip "Astuce"
    Ceci est une astuce verte.

!!! warning "Attention"
    Ceci est un avertissement orange.

!!! danger "Danger"
    Ceci est un avertissement rouge.

!!! info "Information fab-c"
    Informations spécifiques fab-c.

!!! example "Exemple"
    Un exemple de code ou d'utilisation.

Boîtes repliables

??? note "Cliquez pour voir plus"
    Contenu caché par défaut.

???+ tip "Ouvert par défaut"
    Contenu visible par défaut mais repliable.

Activer dans mkdocs.yml

Assure-toi d'avoir dans markdown_extensions :

markdown_extensions:
  - admonition
  - pymdownx.details
  - pymdownx.superfences

7. Galeries d'images

Afficher des images côte à côte

Dans tes pages Markdown :

<div class="galerie">
  <img src="image1.jpg" alt="Image 1">
  <img src="image2.jpg" alt="Image 2">
  <img src="image3.jpg" alt="Image 3">
</div>

Ajoute dans docs/stylesheets/extra.css :

/* Galerie d'images */
.galerie {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  gap: 1rem;
  margin: 2rem 0;
}

.galerie img {
  width: 100%;
  height: 250px;
  object-fit: cover;
  border-radius: 8px;
  transition: transform 0.3s;
}

.galerie img:hover {
  transform: scale(1.05);
  box-shadow: 0 5px 15px rgba(0,0,0,0.3);
}

8. Cartes de projets (style fab-c)

CSS pour les cartes

Dans docs/stylesheets/extra.css :

/* Grille de projets */
.projet-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
  gap: 2rem;
  margin: 2rem 0;
}

.projet-card {
  background: var(--md-code-bg-color);
  border-radius: 8px;
  overflow: hidden;
  transition: transform 0.3s, box-shadow 0.3s;
  border: 1px solid var(--md-default-fg-color--lightest);
}

.projet-card:hover {
  transform: translateY(-5px);
  box-shadow: 0 10px 30px rgba(0,0,0,0.2);
}

.projet-card img {
  width: 100%;
  height: 200px;
  object-fit: cover;
}

.projet-card-content {
  padding: 1.5rem;
}

.projet-card h3 {
  margin: 0 0 0.5rem 0;
  color: #003D7A;
}

.projet-card p {
  margin: 0 0 1rem 0;
  color: var(--md-default-fg-color--light);
}

.projet-btn {
  display: inline-block;
  padding: 0.5rem 1rem;
  background: #00A9E0;
  color: white !important;
  text-decoration: none;
  border-radius: 4px;
  font-weight: 500;
  transition: background 0.3s;
}

.projet-btn:hover {
  background: #003D7A;
}

Utilisation dans une page

<div class="projet-grid">
  <div class="projet-card">
    <img src="images/projet1.jpg" alt="Projet 1">
    <div class="projet-card-content">
      <h3>Nom du projet</h3>
      <p>Description courte du projet</p>
      <a href="lien-vers-projet.md" class="projet-btn">Voir le projet →</a>
    </div>
  </div>

  <div class="projet-card">
    <img src="images/projet2.jpg" alt="Projet 2">
    <div class="projet-card-content">
      <h3>Autre projet</h3>
      <p>Description</p>
      <a href="autre-projet.md" class="projet-btn">Voir le projet →</a>
    </div>
  </div>
</div>

9. Configuration avancée

Ajouter Google Analytics (optionnel)

extra:
  analytics:
    provider: google
    property: G-XXXXXXXXXX  # Ton code Google Analytics

Désactiver "Made with Material for MkDocs"

extra:
  generator: false

Ajouter un lien "Éditer cette page"

repo_url: https://gitlab.com/sylden73/documentations
repo_name: fab-c/documentations

theme:
  features:
    - content.action.edit

edit_uri: edit/main/docs/

Ajoute un bouton "Éditer cette page" qui pointe vers GitLab.

10. Extensions Markdown utiles

Tableaux

Déjà activé avec markdown_extensions: - tables

| Machine | Statut | Prix |
|---------|--------|------|
| Laser   | ✅     | 20€  |
| 3D FDM  | ✅     | 5€   |

Listes de tâches

Ajoute dans markdown_extensions :

markdown_extensions:
  - pymdownx.tasklist:
      custom_checkbox: true

Utilisation :

- [x] Tâche terminée
- [ ] Tâche à faire
- [ ] Autre tâche

Surbrillance de texte

markdown_extensions:
  - pymdownx.mark
  - pymdownx.caret
  - pymdownx.tilde