Les Pages Wiki sur GitLab : Centraliser votre documentation logicielle
La mémoire de votre projet
Le code source n'est que la partie émergée de l'iceberg. Pour qu'un projet vive longtemps et soit compréhensible par tous, il a besoin d'une documentation solide. Le Wiki de GitLab est l'outil parfait pour cela : il permet de créer une véritable encyclopédie interne pour votre dépôt.
Contrairement au fichier README.md qui reste souvent technique et limité à un seul fichier, le Wiki permet de structurer des dizaines de pages (guides d'installation, règles de contribution, architecture logicielle). C'est un espace collaboratif où chaque membre de l'équipe peut apporter sa pierre à l'édifice.
| Rôle utilisateur | Action sur le Wiki |
|---|---|
| Guest (Invité) | Lecture seule des pages |
| Reporter | Lecture seule des pages |
| Developer / Maintainer | Création et édition autorisées |
Créer une page Wiki pas à pas
Pas besoin de maîtriser des outils complexes : si vous savez écrire du texte, vous savez documenter votre projet sur GitLab.
Accéder à l'espace Wiki
Depuis votre projet, repérez et cliquez sur l'onglet Plan puis Wiki dans le menu latéral. Si c'est votre première visite, GitLab vous proposera de créer votre première page Wiki.
"L'onglet Wiki est situé juste à côté de Plan"
Rédaction et mise en forme
Remplissez les informations de votre nouvelle page :
- Title : Donnez un nom clair à votre page (ex : "Guide d'installation"). C'est le titre qui apparaîtra en haut de votre documentation logicielle.
- Path : GitLab génère automatiquement l'adresse URL à partir du titre. Vous pouvez décocher la case Generate page path from title si vous souhaitez personnaliser manuellement le lien d'accès.
- Format : Par défaut, le Markdown est sélectionné. C'est le langage standard pour mettre en forme vos textes (gras, titres, listes) très simplement.
- Template : Une nouveauté majeure qui permet de choisir un modèle de page pré-rempli pour gagner du temps et garder une structure cohérente sur tout le Wiki de GitLab.
- Content : C'est votre zone de travail. Vous pouvez utiliser l'éditeur visuel ou cliquer sur Switch to plain text editing pour rédiger directement en code Markdown.
- Commit message : Comme pour une modification de code, rédigez une courte phrase expliquant l'ajout ou la modification de la page (ex : "Création de la documentation réseau").
Cliquez sur le bouton bleu Create page pour enregistrer votre travail.
Consultation du résultat
Votre page est désormais en ligne. Vous pouvez voir l'historique des modifications, ce qui est très pratique pour savoir qui a mis à jour la documentation et quand.
"Votre documentation est maintenant accessible à toute l'équipe"
Information technique
Techniquement, le Wiki est un dépôt Git séparé. Cela signifie que les utilisateurs avancés peuvent même cloner le Wiki sur leur ordinateur pour rédiger la documentation hors-ligne et la pousser comme s'il s'agissait de code classique.
Conclusion
Utiliser les Pages Wiki transforme votre dépôt en un projet professionnel et pérenne. Une bonne documentation réduit drastiquement le temps d'apprentissage des nouveaux arrivants et évite les erreurs dues au manque d'informations.
Maintenant que votre projet est complet (code, tickets, jalons et documentation), il ne faut pas oublier l'essentiel : la sécurité de vos données. Dans le prochain chapitre, nous allons apprendre à créer une sauvegarde GitLab (Backup) pour ne jamais rien perdre.
Espace commentaire
Écrire un commentaire
Rejoignez la discussion
Vous devez être connecté pour poster un message.
25 commentaires
Oui, le wiki est inclus dans le dump généré par
gitlab-backup create. Tu n'as rien de spécial à configurer de ton côté.On peut automatiser la sauvegarde de ce repo wiki avec le reste des backups ?
Normal, GitLab sanitize les titres. Garde des titres simples, sans accent ni espace, et utilise la case
Pathpour définir l'URL propre :J'ai un souci avec les caractères spéciaux dans les noms de pages. Ça me génère des URL illisibles.
Le support des templates est vraiment un gain de temps pour harmoniser la doc.
Non, le wiki est géré globalement au niveau du dépôt. Soit tu as l'accès en écriture, soit tu ne l'as pas. C'est tout ou rien.
Est-ce qu'on peut restreindre l'accès en écriture à certains dossiers du wiki ?
L'historique est vraiment pratique pour éviter les suppressions accidentelles par des juniors.
J'ai testé l'éditeur visuel, il me transforme tout mon Markdown en balises bizarres. Je reste sur le mode
plain text.Utilise les chemins relatifs basés sur la racine du wiki. Si ta page est dans un sous-dossier, remonte avec
../. Évite les liens absolus à tout prix.Comment on fait pour lier deux pages ensemble ? J'ai essayé avec des chemins relatifs mais ça casse dès que je change la structure.
C'est exactement l'idée. Tout est dans le repo, donc c'est versionné. Voici comment vérifier l'historique en CLI si t'as cloné le repo :
Franchement, le Wiki GitLab est plus simple que Confluence pour les petits projets. Au moins c'est versionné.
Le rendu Markdown est parfois différent entre le README et le Wiki. C'est normal ?
C'est comme pour le code source. Fais un
git pull --rebaseavant de pousser. Si y'a des modifs sur l'interface web en même temps, tu vas te manger des conflits.J'ai tenté de cloner le wiki en local pour éditer hors-ligne, mais j'ai un conflit lors du
git push. Comment gérer ça proprement ?Est-ce qu'on peut forcer un modèle de page par défaut pour tous les nouveaux wikis ?
Merci, c'était bien désactivé dans les paramètres du projet. Ça marche nickel maintenant.
Non, c'est disponible sur toutes les versions. Regarde dans les Settings > General > Visibility, project features, permissions. Vérifie que le bouton Wiki est bien sur
Enabled.Je ne vois pas l'onglet Wiki dans mon menu latéral. Je suis sur la version Community Edition, c'est bridé ?
Pour l'API, tu peux passer par les points de terminaison
POST /projects/:id/wikis. C'est du classique.Pour les schémas, intègre des fichiers
.pngdirectement dans le dossier du repo wiki, ça passe sans souci.Le markdown c'est bien, mais pour des gros schémas, le wiki GitLab devient vite limité, non ?
Quelqu'un sait si on peut scripter la création de pages via l'API ? J'ai une centaine de projets à documenter.
T'as bien vérifié ton accès via HTTPS ou SSH ? Le wiki est un repo Git distinct. Si t'as un souci, essaie de forcer le clone avec l'URL dédiée au wiki, elle se termine par
.wiki.git.Tuto utile. Par contre, j'ai voulu cloner le wiki comme un repo standard, mais j'ai une erreur de permission. Pourtant je suis bien en Maintainer sur le projet.