Mise en place de l'environnement documentaire

1. Contexte et Objectifs

Mise en place d'un portfolio de compétences numérique pour documenter les travaux réalisés durant le BTS SIO. Exigences : pérenne (reste disponible après le BTS), versionné (traçabilité des modifications), accessible en ligne (consultation par formateurs et recruteurs).

L'objectif est de mettre en œuvre une chaîne DevOps complète : rédaction en Markdown, versionnement Git, hébergement GitLab, génération automatique via MkDocs, déploiement continu via GitLab Pages. Ce workflow simule les pratiques professionnelles de documentation technique.

2. Besoins identifiés

Rédaction rapide et portable : Format Markdown lisible en texte brut, éditable avec n'importe quel éditeur, compatible tous systèmes (Windows, Linux, macOS). Standard de l'industrie (GitHub, Stack Overflow).

Versionnement et traçabilité : Git garantit un historique complet des versions. Chaque commit est horodaté, signé, avec message explicatif. Possibilité de rollback en cas d'erreur.

Génération automatique du site : MkDocs transforme automatiquement le Markdown en site web HTML professionnel avec navigation, recherche, thème responsive. Transformation automatique à chaque push Git via pipeline CI/CD.

Accessibilité publique : GitLab Pages héberge gratuitement le site et attribue une URL publique (format https://username.gitlab.io/projet). URL partageable sur CV, disponible 24/7.

Apprentissage Linux CLI : Utilisation de Debian en ligne de commande pour installer et configurer les outils. Développe les compétences en administration système (serveurs distants, conteneurs, pipelines).

3. Solution technique

Architecture : Chaîne de publication automatisée (pipeline CI/CD) où chaque modification déclenche une régénération complète du site web.

Workflow : Rédaction Markdown (VSCode) → Versionnement (Git) → Push (GitLab) → Build automatique (MkDocs) → Déploiement (GitLab Pages) → Site public accessible

Stack technique :

  • VSCode : Éditeur open-source avec extensions Markdown (prévisualisation temps réel, intégration Git). Choisi pour sa légèreté et son support multiplateforme.

  • Markdown : Format texte brut lisible sans transformation, syntaxe minimaliste (# titres, - listes). Standard de l'industrie. Alternative à HTML (trop verbeux) et Word (format binaire non versionnable).

  • Git : Gestionnaire de versions standard (85% des entreprises tech). Historique complet, travail hors ligne, branching. Alternative à SVN (obsolète) et Google Drive (pas de vraie gestion de versions).

  • GitLab : Hébergement Git avec CI/CD intégré et GitLab Pages gratuit. Alternative à GitHub (CI/CD moins intégré) et hébergement classique (pas d'automatisation).

  • MkDocs : Générateur de site statique spécialisé documentation. Configuration minimale (mkdocs.yml), thèmes professionnels, génération rapide. Alternative à Jekyll (complexe) et HTML manuel (chronophage).

  • Debian CLI : Environnement léger sans GUI, apprentissage des fondamentaux Linux (navigation, apt, droits). Préparation aux environnements serveurs réels.

Pipeline CI/CD : Fichier .gitlab-ci.yml déclenche automatiquement : installation Python/MkDocs → mkdocs build → publication sur GitLab Pages. Zéro intervention manuelle après le push.

4. Réalisation

Phase 1 : Installation de l'environnement

VSCode : Installation depuis code.visualstudio.com avec extensions Markdown All in One, GitLens, French Language Pack.

Git : Installation Git for Windows, configuration identité :

git config --global user.name "Prenom Nom"
git config --global user.email "email@exemple.com"

GitLab : Création compte sur gitlab.com, nouveau projet en mode Public, récupération URL du dépôt.

Phase 2 : Configuration DevOps

Initialisation Git local :

mkdir portfolio-bts-sio
cd portfolio-bts-sio
git init
git remote add origin https://gitlab.com/username/portfolio.git

Structure créée : docs/ (contenu Markdown), mkdocs.yml (configuration), .gitlab-ci.yml (pipeline).

Configuration MkDocs :

sudo apt install python3 python3-pip -y
pip3 install mkdocs mkdocs-material

Fichier mkdocs.yml :

site_name: Portfolio BTS SIO
theme:
  name: material
nav:
  - Accueil: index.md
  - Situations: situations/index.md

Pipeline CI/CD (.gitlab-ci.yml) :

image: python:3.9-alpine
pages:
  script:
    - pip install mkdocs mkdocs-material
    - mkdocs build --site-dir public
  artifacts:
    paths:
      - public

Phase 3 : Rédaction et publication

Rédaction des fiches en Markdown dans docs/, ajout des captures dans docs/images/.

Workflow Git quotidien :

git status
git add docs/
git commit -m "Ajout fiche Gestion du Parc"
git push origin main

Le push déclenche automatiquement le pipeline. Site accessible quelques secondes après à https://username.gitlab.io/portfolio.

5. Preuves de réalisation

Capture 1 : Code source Markdown dans VSCode

Fiche Markdown VSCode

Légende : Code source Markdown de la fiche "Mise en place documentaire" dans VSCode. Structure visible avec titres hiérarchisés (##), listes (tirets -), mots-clés en gras (**VSCode**), liens vers captures (![](../Images/)). Le fil d'Ariane en haut montre l'arborescence : docs > 03_Support > Mise_en_place_documentaire.md. Le panneau gauche affiche la structure complète du projet. Démontre la maîtrise de la syntaxe Markdown et l'organisation en dossiers.

Capture 2 : Historique Git (GitGraph)

GitGraph historique

Légende : Historique Git montrant la ligne de temps des commits avec identifiant (hash), auteur, date, et message. Progression chronologique visible : création du projet, ajouts de fiches, corrections. Messages de commit explicites ("Ajout fiche Gestion du Parc", "Correction orthographe"). Prouve l'utilisation rigoureuse de Git comme outil de versionnement avec traçabilité complète et possibilité de rollback.

Capture 3 : Pipeline GitLab CI/CD et déploiement

Pipeline GitLab

Légende : Interface GitLab montrant le suivi des livrables avec l'URL publique du site (https://portefeuilles-competence-*.gitlab.io) fonctionnelle et accessible. Statut "Rendu Conforme" avec évaluation 17/20. Dates de rendu visibles ("depuis 3 mois", "depuis 4 mois"). Valide que le pipeline CI/CD a déployé le site avec succès sur GitLab Pages et que l'URL reste accessible en permanence, répondant à l'exigence de pérennité.