Guide d'installation : Documentation fab-c avec Obsidian + GitLab Pages

Auteur : Sylvain Denis - fab-c
Date : Avril 2026
Système : 100% gratuit, sauvegarde locale, publication automatique

Vue d'ensemble du système

Qu'est-ce qu'on construit ?

Un système de documentation qui permet de :

✅ Écrire facilement dans Obsidian (interface type Notion)
✅ Sauvegarder localement (dossier sur ton PC)
✅ Sauvegarder automatiquement sur GitLab (cloud + versioning)
✅ Publier automatiquement un site web
✅ Tout ça gratuitement et sans ligne de commande au quotidien

Schéma du workflow

TON PC (Linux)
    ↓ Édition facile
Obsidian
    ↓ Sauvegarde auto (toutes les 5 min)
GitLab (cloud)
    ↓ Build automatique (2-3 min)
GitLab Pages (site web)
    ↓ Accessible publiquement
https://sylden73.gitlab.io/documentations/

Avantages

Édition simple : interface graphique type Notion
Sauvegarde locale : tout dans un dossier que tu peux copier
Backup cloud : GitLab garde tout + historique complet
Publication automatique : modifie → attends 5-8 min → c'est en ligne
100% gratuit : Obsidian gratuit, GitLab gratuit, GitLab Pages gratuit
Markdown portable : si un jour tu changes d'outil, tu gardes tout

Prérequis

Avant de commencer, tu dois avoir :

Sur ton PC (Linux)

[x] Git installé

git --version
# Doit afficher : git version 2.x.x

# Si pas installé :
sudo apt install git  # Ubuntu/Debian
sudo dnf install git  # Fedora

[x] Obsidian installé
- Télécharge depuis https://obsidian.md
- Ou via Flatpak, AppImage, etc.
- [x] Git configuré avec ton identité
```
git config --global user.name "Ton Nom"
git config --global user.email "ton.email@example.com"
```

Sur GitLab

[x] Compte GitLab (gratuit)
- Si tu n'en as pas : https://gitlab.com/users/sign_up
- Utilise ton email professionnel ou personnel

Installation complète (étape par étape)

Point 1 : Créer le projet GitLab

Pourquoi ? GitLab va héberger ton code et générer ton site web.

Va sur gitlab.com et connecte-toi
Clique sur "New project" (ou "Nouveau projet")
Choisis "Create blank project" (Créer un projet vide)

Configuration du projet :

Nom du projet : documentations (ou le nom que tu veux)
URL : laisse ton username
Visibilité : Public (obligatoire pour GitLab Pages gratuit)
Initialize repository with a README : ✅ COCHE cette case
Clique sur "Create project"

Résultat attendu : Tu as maintenant un projet GitLab avec une URL comme :

https://gitlab.com/ton-username/documentations

Note l'URL pour l'étape suivante (tu en auras besoin).

Point 2 : Cloner le projet sur ton PC

Pourquoi ? On va télécharger le projet GitLab sur ton PC pour y travailler.

Ouvre un terminal

Va dans le dossier où tu veux stocker ton projet

cd ~/Documents
# ou ~/Projets, ou n'importe où

Clone le projet GitLab

# Remplace par TON URL GitLab
git clone https://gitlab.com/ton-username/documentations.git

# Entre dans le dossier
cd documentations

Crée la structure de dossiers pour Obsidian et MkDocs

# Crée le dossier docs (où seront tes fichiers Markdown)
mkdir -p docs/projets-numeriques docs/projets-laser docs/machines docs/coderdojo

# Crée un dossier .obsidian pour marquer ce dossier comme vault Obsidian
mkdir .obsidian

Vérifie la structure
```
ls -la
```
Tu devrais voir :
- .git/ (dossier Git, caché)
- .obsidian/ (dossier Obsidian, caché)
- docs/ (ton contenu)
- README.md (créé par GitLab)

Résultat attendu : Tu as maintenant un dossier documentations sur ton PC avec la structure prête.

Point 3 : Ouvrir le projet dans Obsidian

Pourquoi ? Obsidian va te permettre d'éditer facilement tes fichiers Markdown.

Lance Obsidian
Ouvre le dossier comme vault
- Clique sur "Open folder as vault" (ou "Ouvrir un dossier comme coffre")
- Navigue jusqu'au dossier documentations que tu viens de cloner
- Sélectionne le dossier documentations (la racine, pas le sous-dossier docs)
- Clique sur "Open"
- Crée une première page de test
Dans Obsidian :
- Dans le panneau de gauche (File explorer), fais clic droit sur le dossier docs
- Sélectionne "New note"
- Nomme-la : index
- Colle ce contenu :
```
# Bienvenue sur la documentation fab-c

Ceci est un test de publication.

## Nos sections

- Projets Numériques
- Projets Laser
- Machines
- CoderDojo Gilly
```
- Sauvegarde (Ctrl+S)
- Vérifie que le fichier est créé
Dans ton terminal :
```
ls docs/
# Doit afficher : index.md
```

Résultat attendu : Obsidian est ouvert sur ton vault et tu as créé ta première page.

Point 4 : Installer et configurer le plugin Obsidian Git

Pourquoi ? Ce plugin va automatiquement sauvegarder tes modifications sur GitLab toutes les 5 minutes.

Étape 4.1 : Installer le plugin

Dans Obsidian :

Ouvre les Paramètres (icône engrenage en bas à gauche, ou Ctrl+,)
Dans le menu de gauche, clique sur "Modules complémentaires" ou "Plugins communautaires"
Si c'est la première fois, clique sur "Activer les plugins communautaires"
Clique sur "Parcourir"
Dans la recherche, tape : Git
Clique sur le plugin "Git" par Vinzent (Denis Olehov)
Clique sur "Installer"
Une fois installé, clique sur "Activer"

Étape 4.2 : Configurer le plugin

Toujours dans Paramètres, trouve "Git" dans la liste des plugins (section en bas)
Clique sur "Git"

Configure ces paramètres importants :

Section "Backup" :

Auto commit-and-sync interval (minutes) : 5
- Explique : Obsidian va sauvegarder automatiquement toutes les 5 minutes
Commit message : sauvegarde auto: {{date}}
- Explique : Le message qui apparaîtra dans l'historique GitLab

Section "Startup" :

Pull updates on startup : ✅ COCHE
- Explique : Au démarrage d'Obsidian, récupère les dernières modifications depuis GitLab

Autres paramètres :

Laisse tout le reste par défaut
Ferme les Paramètres

Résultat attendu : Le plugin Git est installé et configuré pour sauvegarder automatiquement toutes les 5 minutes.

Point 5 : Faire le premier push vers GitLab

Pourquoi ? On doit initialiser la connexion entre ton PC et GitLab.

Cette étape se fait en ligne de commande (une seule fois).

Ouvre un terminal dans le dossier documentations
```
cd ~/chemin/vers/documentations
```
Ajoute tous les fichiers
```
git add .
```
Explique : Prépare tous les fichiers pour l'envoi
Crée le premier commit
```
git commit -m "Premier commit - initialisation Obsidian"
```
Explique : Enregistre une "photo" de l'état actuel
Envoie vers GitLab
```
git push -u origin main
```
Explique : Envoie tout sur GitLab

GitLab va demander :
- Username : ton email GitLab (ex: sylvain.denis@ulb.be)
- Password : ton mot de passe GitLab
Si tu as l'authentification à deux facteurs (2FA) :
- Tu devras créer un Personal Access Token sur GitLab
- Va dans GitLab → Settings → Access Tokens
- Crée un token avec le scope write_repository
- Utilise ce token comme mot de passe
- Vérifie le succès
Tu devrais voir :
```
To https://gitlab.com/ton-username/documentations.git
   xxxxx..xxxxx  main -> main
la branche 'main' est paramétrée pour suivre 'origin/main'.
```
Vérifie sur GitLab
- Va sur https://gitlab.com/ton-username/documentations
- Tu devrais voir ton dossier docs/ et le fichier index.md

Résultat attendu : Ton code est maintenant sur GitLab. Le plugin Obsidian Git va maintenant gérer les push automatiquement.

Point 6 : Créer les fichiers de configuration

Pourquoi ? Ces fichiers disent à GitLab comment générer ton site web.

Étape 6.1 : Créer mkdocs.yml

Ce fichier configure MkDocs (le générateur de site).

Dans ton terminal :

cd ~/chemin/vers/documentations

Crée le fichier mkdocs.yml avec ton éditeur préféré :

nano mkdocs.yml
# ou gedit mkdocs.yml
# ou kate mkdocs.yml

Colle ce contenu :

# Configuration du site
site_name: fab-c Documentation
site_url: https://ton-username.gitlab.io/documentations/
site_author: Ton Nom
site_description: Documentation des projets fab-c - FabLab ULB Charleroi

# Thème Material Design
theme:
  name: material
  language: fr
  palette:
    primary: blue
    accent: orange
  features:
    - navigation.instant      # Chargement rapide des pages
    - navigation.sections     # Sections dans la sidebar
    - navigation.top          # Bouton retour en haut
    - search.suggest          # Suggestions de recherche
    - search.highlight        # Surligner les résultats

# Extensions Markdown (pour tableaux, émojis, etc.)
markdown_extensions:
  - attr_list              # Attributs sur les éléments
  - md_in_html             # Markdown dans HTML
  - tables                 # Tableaux
  - admonition             # Boîtes d'avertissement
  - pymdownx.details       # Sections repliables
  - pymdownx.superfences   # Blocs de code avancés
  - pymdownx.emoji:        # Support émojis
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg

# Pas de navigation manuelle = navigation automatique depuis la structure de dossiers
# MkDocs va suivre exactement ta structure Obsidian

Note importante : Remplace ton-username par ton vrai username GitLab dans site_url.

Sauvegarde et ferme (Ctrl+X, Y, Entrée si nano).

Étape 6.2 : Créer .gitlab-ci.yml

Ce fichier dit à GitLab comment construire ton site automatiquement.

nano .gitlab-ci.yml

Colle ce contenu :

# Image Docker avec Python pour MkDocs
image: python:3.11

# Job "pages" = GitLab Pages
pages:
  stage: deploy
  script:
    # Installe MkDocs avec le thème Material
    - pip install mkdocs-material

    # Génère le site HTML dans le dossier "public"
    - mkdocs build --site-dir public

  # Les fichiers à publier
  artifacts:
    paths:
      - public

  # Ne lance que sur la branche main
  only:
    - main

Sauvegarde et ferme.

Résultat attendu : Tu as créé 2 fichiers de configuration à la racine de ton projet.

Point 7 : Créer les pages index pour les sections

Pourquoi ? Pour éviter les erreurs 404, chaque section doit avoir une page d'accueil.

Tu peux faire ça dans Obsidian :

Dans le dossier docs/projets-numeriques, crée une note nommée index
Écris : # Projets Numériques
Répète pour chaque section :
- docs/projets-laser/index.md → # Projets Laser
- docs/machines/index.md → # Machines
- docs/coderdojo/index.md → # CoderDojo Gilly

Résultat attendu : Chaque dossier a maintenant une page d'accueil.

Point 8 : Envoyer tout sur GitLab

Dans ton terminal :

git add .
git commit -m "Configuration GitLab Pages + MkDocs"
git push

Explique : On envoie les fichiers de configuration sur GitLab

Résultat attendu : GitLab va détecter les nouveaux fichiers et lancer automatiquement la construction du site.

Point 9 : Vérifier que le site est en ligne

Étape 9.1 : Vérifier le pipeline

Va sur https://gitlab.com/ton-username/documentations
Menu de gauche : "Construire" → "Pipelines"
Tu devrais voir un pipeline :
- En cours (icône bleue qui tourne) → attends 1-2 minutes
- Terminé avec succès (icône verte ✓) → parfait !
- En erreur (icône rouge ✗) → clique dessus pour voir l'erreur

Étape 9.2 : Accéder au site

Menu de gauche : "Déployer" → "Pages"
Tu verras l'URL de ton site : https://ton-username.gitlab.io/documentations/
Clique sur le lien

Résultat attendu : Ton site s'affiche avec "Bienvenue sur la documentation fab-c" ! 🎉

Vérification finale : Tout fonctionne ?

Test 1 : Modification depuis Obsidian

Dans Obsidian, modifie docs/index.md (ajoute une ligne)
Sauvegarde (Ctrl+S)
Attends 5 minutes (le plugin Git va push automatiquement)
Attends 2-3 minutes (GitLab reconstruit le site)
Rafraîchis ton site : https://ton-username.gitlab.io/documentations/
✅ Ta modification est visible !

Test 2 : Ajouter une nouvelle page

Dans Obsidian, crée docs/projets-numeriques/mon-projet.md
Écris du contenu
Sauvegarde
Attends 5-8 minutes
Rafraîchis le site
✅ La page apparaît dans le menu !

Résumé du workflow quotidien

Une fois installé, voici comment tu travailles au quotidien :

Ouvre Obsidian sur ton vault documentations
Crée/modifie tes pages dans le dossier docs/
Sauvegarde (Ctrl+S)
C'est tout !
- Le plugin Git sauvegarde automatiquement toutes les 5 min
- GitLab reconstruit automatiquement le site
- Ton site est à jour 7-8 minutes après ta modification

Tu n'as jamais besoin de toucher au terminal au quotidien.

Sauvegarde et sécurité

Où sont tes données ?

Local : dossier ~/chemin/vers/documentations sur ton PC
- Backup manuel : copie ce dossier sur USB/NAS/Cloud perso
- GitLab : https://gitlab.com/ton-username/documentations
- Backup automatique avec historique complet (Git)
- Tu peux récupérer n'importe quelle version passée

Comment récupérer tout si ton PC plante ?

Installe Git + Obsidian sur le nouveau PC

Clone le projet :

git clone https://gitlab.com/ton-username/documentations.git

Ouvre dans Obsidian
Réinstalle le plugin Git
✅ Tu as tout récupéré !

Dépannage

Le plugin Git ne push pas automatiquement

Vérifications :

Paramètres → Git → "Auto commit-and-sync interval" est bien à 5
Redémarre Obsidian
Fais un commit manuel pour tester : Palette de commandes → Git: Commit all changes

Le site ne se met pas à jour

Vérifications :

GitLab → Pipelines → le dernier pipeline est vert ✓ ?
Si rouge ✗, clique dessus pour voir l'erreur
Attends bien 2-3 minutes après le push
Rafraîchis avec Ctrl+F5 (vidage du cache)

Erreur 404 sur une page

Cause : Le fichier n'existe pas ou le nom est mal orthographié

Solution : Vérifie dans Obsidian que le fichier existe bien dans docs/

Support

Documentation MkDocs Material : https://squidfunk.github.io/mkdocs-material/
Documentation Obsidian : https://help.obsidian.md
Documentation GitLab Pages : https://docs.gitlab.com/ee/user/project/pages/

Félicitations ! Tu as maintenant un système de documentation professionnel, gratuit et automatisé ! 🎉