Organiser shelves, books et chapters BookStack : best practices 2026

📍 Article principal de la série : BookStack 2026 : guide pratique.

Sans structure planifiée, BookStack devient un fouillis après 6 mois. Ce tutoriel détaille l’architecture validée chez plusieurs PME francophones : shelves par grand domaine, books par sujet, chapters par étape.

Prérequis

• BookStack en production.
• Compréhension besoins documentation entreprise.
• Niveau attendu : intermédiaire.
• Temps estimé : 1-2 heures planification.

Pour structurer un wiki BookStack qui survit 5+ ans, vous avez besoin d’une instance fonctionnelle (voir notre tutoriel d’installation Coolify). Au moins 50 pages de contenu déjà existantes pour valider la structure (en dessous, attendez d’avoir une masse critique). Une équipe éditoriale de 2-3 personnes engagées sur la maintenance. Comptez 4-8 heures de travail initial pour designer la taxonomie et migrer les pages existantes vers la nouvelle structure.

Architecture par type d’entreprise

SaaS B2B

• Shelf « Public Documentation » : Books par feature.
• Shelf « Internal Engineering » : Books par stack.
• Shelf « Onboarding » : Books par rôle.
• Shelf « Procédures » : Books par processus.

Cabinet juridique

• Shelf « Procédures Internes ».
• Shelf « Modèles & Templates ».
• Shelf « Veille Juridique ».
• Shelf « Onboarding ».

ESN/Agence digitale

• Shelf par client (privé).
• Shelf « DevOps Runbooks ».
• Shelf « Process Internes ».
• Shelf « Connaissance Tech ».

Étape 1 — Créer shelves

Sidebar → Shelves → Create new shelf. Pour chacun :

• Name descriptif.
• Description claire.
• Cover image.
• Tags : internal, public, tech.

Les Shelves sont le niveau supérieur d’organisation. Limitez-les à 5-8 maximum pour préserver la lisibilité. Pour une PME tech, la structure type : Onboarding (accueil nouveaux), Process (workflows internes), Documentation produit, Équipe (RH, équipement), Externe (clients, partenaires), Archives. Évitez les noms vagues (Divers, Misc, Documents) qui finissent par accumuler tout et son contraire. Chaque Shelf doit répondre à une question claire (Comment fonctionne X chez nous ?).

Étape 2 — Books par sujet

Dans shelf Engineering, books typiques :

• Déploiement Production.
• Stack Frontend.
• Stack Backend.
• Bases de données.
• Monitoring.
• Incident Response.

Dans chaque Shelf, créez 3-7 Books qui cassent le sujet en sous-thèmes cohérents. Dans Onboarding : Premier jour, Premier mois, Outils, Politique. Dans Process : Recrutement, Achats, Ventes, Support client. Un Book contient idéalement 5-30 pages. Au-delà, splittez en deux Books. Cette granularité empêche que 200 pages s’accumulent sous un seul Book qui devient illisible.

Étape 3 — Chapters par étape

Book « Déploiement Production » → chapters :

• 1. Préparation du VPS.
• 2. Configuration DNS.
• 3. Coolify setup.
• 4. CI/CD.
• 5. Monitoring post-deploy.

Les Chapters sont un niveau optionnel sous les Books. Utilisez-les pour les Books qui couvrent un processus en plusieurs étapes (Recrutement → Sourcing → Tri CV → Entretiens → Décision → Onboarding). Sans Chapter, listez juste les pages plates. Évitez la sur-hiérarchisation : un wiki où il faut 4 clics pour atteindre une info utile sera abandonné par les utilisateurs au profit de Slack ou WhatsApp.

Étape 4 — Pages : action concrète

Chapter « Préparation du VPS » → pages :

• Acheter VPS Hetzner CX22.
• Configurer SSH key et UFW.
• Mises à jour automatiques.
• Monitoring Uptime Kuma.

Chaque Page doit répondre à une question opérationnelle précise. Mauvais titre : Sécurité. Bon titre : Comment réagir si un employé clique sur un lien de phishing. Cette discipline transforme le wiki d’une encyclopédie inutile en outil opérationnel. Pour 100 pages dans une PME à Plateau, viser 80 % de pages action (procédures, runbooks, FAQ) et 20 % de pages référence (politiques, glossaires).

Étape 5 — Templates de pages

# Titre procédure

## Contexte
[Pourquoi cette procédure existe]

## Prérequis
- Item 1
- Item 2

## Étapes
1. Étape 1
2. Étape 2

## Vérification
[Comment vérifier]

## Erreurs courantes
[Issues fréquentes]

## Liens
- [Page liée](url)

BookStack permet de créer des templates depuis Settings → Templates. Créez 5-10 templates pour les types de pages récurrents : Procédure (objectif, étapes, validation), Onboarding employé, Post-mortem incident, Review produit. Lors de la création d’une nouvelle page, l’utilisateur choisit le template et obtient une structure pré-remplie. Cette discipline assure la cohérence visuelle et accélère la rédaction de 50 %.

Étape 6 — Tags et metadata

Tags par page : aws, postgres, incident, onboarding. Filtrable search.

BookStack supporte les tags depuis 2020. Tagguez chaque page avec 2-5 mots-clés (department:rh, type:procedure, status:draft). Les tags facilitent la recherche transversale qui transcende la hiérarchie Shelf/Book/Chapter. Configurez Settings → Tags pour suggérer une liste contrôlée plutôt que laisser chacun inventer ses tags. Sans contrôle, vous accumulez 200 tags semi-doublons (rh, RH, Ressources humaines, hr) qui ne servent à rien.

Étape 7 — Cross-references

BookStack support liens internes auto. Taper [ ouvre suggestion pages. Maillage fluide.

Les liens entre pages sont le tissu conjonctif du wiki. Quand vous mentionnez un autre process, liez-le. BookStack propose l’autocomplete des liens internes via @mention. Vérifiez les liens cassés trimestriellement avec un outil comme broken-link-checker. Pour les pages référencées par 5+ autres pages, ajoutez un encadré ‘Voir aussi’ en bas avec les liens entrants principaux. Cette discipline crée un graphe de connaissances vivant.

Étape 8 — Page sommaire

Première page de chaque book = sommaire des chapters. Aide navigation.

Pour chaque Book contenant 10+ pages, créez une page Sommaire avec liens vers les sections majeures. BookStack le génère partiellement automatiquement, mais une version éditoriale (avec descriptions courtes pour chaque lien) améliore l’expérience. C’est aussi la page que vous citez en onboarding (lis ce sommaire, tu sauras où chercher quoi). Le retour sur investissement est élevé.

Étape 9 — Reviews trimestrielles

Tous les 3 mois, relire sections. Pages obsolètes archivées. Évite drift.

Tous les 3 mois, programmez une session de 2-3 heures avec l’équipe éditoriale pour passer en revue 30-50 pages aléatoires. Vérifiez : info encore d’actualité ? Liens externes encore valides ? Captures d’écran encore à jour ? Personnes mentionnées encore en poste ? Marquez les pages obsolètes en draft ou déplacez vers le Shelf Archives. Sans cette discipline, le wiki accumule de la dette informationnelle qui le rend progressivement inutile.

Étape 10 — Search optimal

• Titres descriptifs.
• Premier paragraphe résume.
• Tags pertinents.

BookStack utilise SQL FULLTEXT par défaut. Pour les wikis volumineux (1000+ pages), activez l’indexation Elasticsearch via le plugin officiel. Configurez les synonymes courants dans votre métier (RH = ressources humaines, dev = développeur). Encouragez les utilisateurs à utiliser la barre de recherche plutôt que la navigation hiérarchique : sur des wikis matures, 70-80 % du trafic vient de la search. Mettez la barre de recherche en évidence sur la page d’accueil.

Erreurs fréquentes

Erreur	Cause	Solution
Trop de profondeur	Hierarchy 5+	Garder 4 max
Pages dupliquées	Pas de search avant	Always search
Permissions chaotiques	Custom roles partout	3-4 rôles standard
Tags inconsistents	Free-text	Liste tags officiels
Doc orpheline	Pas de review	Quarterly review

Quatre pièges classiques. Premièrement, créer trop de Shelves (10+) qui produit un menu illisible. Deuxièmement, dupliquer des pages entre Books sans deduplication ce qui crée des sources de vérité conflictuelles. Troisièmement, laisser des draft accumulés depuis 6 mois (publiez ou supprimez, pas de zone grise). Quatrièmement, négliger les permissions et exposer des infos sensibles à toute l’organisation.

Spécificités Afrique de l’Ouest francophone

Trois précisions. Multi-langues : pour PME bilingue FR/AR, shelves séparés. Onboarding : shelf dédié avec book par rôle. Compliance : shelf « Conformité ARTCI/CDP ».

Pour une équipe à Dakar ou Cotonou, deux particularités. Premièrement, le bilinguisme : si une partie du contenu est en anglais (références techniques, doc fournisseurs), créez des Shelves séparés FR et EN plutôt que de mélanger. Deuxièmement, les contraintes de connectivité : pour les utilisateurs en zone rurale ou en mobilité, l’app mobile BookStack (PWA) permet la consultation hors-ligne — activez-la dans les settings.

Tutoriels frères

• Déployer BookStack
• Permissions workflow

BookStack se complète bien avec d’autres outils. Outline pour la rédaction collaborative live (BookStack est plutôt async). Mattermost pour les discussions qui complètent la connaissance écrite. Authentik pour le SSO unifié. CrowdSec pour la protection contre les bots de scraping qui aspirent les wikis. Cette stack collaborative cohérente forme une infrastructure mature pour PME ouest-africaines.

FAQ

Pages max ? CX22 = 50k confortable.

Réorganiser ? Drag-drop reorder. Liens auto-update.

Templates ? Mark as template, réutilisable.

Versioning ? Toute édition crée version.

Doc public partiel ? Public role + shelf privé/public.

Q : Combien de pages avant de structurer ? R : Au-dessus de 50 pages, la structure devient critique. Avant, l’arborescence improvisée fonctionne. Q : Multi-langue ? R : BookStack ne propose pas de système de traductions automatiques entre pages. Solution : Books ou Shelves dédiés à chaque langue. Q : Versionning ? R : Oui, BookStack garde l’historique de chaque page, permet de revoir et restaurer.

Sur un angle proche

• 🔝 Retour au guide général : guide pratique BookStack 2026

Pour creuser la knowledge management, voyez nos tutoriels d’organisation de la documentation produit, gestion des post-mortems d’incidents, rédaction de runbooks opérationnels, et templates pour onboarding nouveaux. Ces patterns appliqués sur 12-24 mois transforment radicalement la productivité et la résilience d’une équipe distribuée.

Étape 1 — Comprendre la hiérarchie shelves, books, chapters, pages

BookStack 24.x impose une structure à quatre niveaux : shelves (étagères) regroupent des books, qui contiennent des chapters, eux-mêmes composés de pages. Cette rigueur est une force pour une PME à Dakar ou Abidjan qui débute en documentation interne : on évite l’arbre Confluence sans fond où plus personne ne retrouve rien.

Avant de créer la moindre page, posez-vous la question : combien de domaines distincts allons-nous documenter sur 12 mois ? Un domaine = une étagère. Trois à six étagères suffisent à 95 % des PME ouest-africaines. Au-delà, vous fragmentez la connaissance.

Étape 2 — Définir les étagères en mode top-down

Listez les grands flux de votre activité, pas les équipes. Une étagère « RH » survit aux réorganisations, une étagère « Direction Mounia » non. Exemple type pour une PME de services numériques à Cotonou :

Shelves :
  - Operations
  - Produit & Tech
  - Commercial & Clients
  - Finance & Compta
  - RH & Onboarding
  - Sécurité & Conformité

Saisissez ces six étagères depuis l’interface en 10 minutes. Sur chaque étagère, ajoutez une description courte (2-3 lignes) qui explique le périmètre. Cette description s’affiche en page d’accueil de l’étagère et oriente le rédacteur futur.

Étape 3 — Cadrer les books et leur granularité

Un book = un sujet cohérent qui se lit du début à la fin. Pas un fourre-tout. Pour l’étagère « Produit & Tech », créez par exemple : Architecture cible, Procédures de déploiement, Runbooks incidents, Onboarding développeur. Chacun fait entre 20 et 80 pages. En dessous de 10 pages, le book est trop maigre : fusionnez-le avec un voisin. Au-delà de 100 pages, il devient illisible : éclatez-le en deux books.

Depuis l’interface BookStack, créez le book puis associez-le à son étagère via le bouton « Add to shelves ». Un même book peut figurer dans plusieurs étagères, utile pour transverse comme Sécurité.

Étape 4 — Structurer les chapters comme des modules de formation

Les chapters sont l’unité didactique. Un chapter = un objectif d’apprentissage atteignable en 15 à 30 minutes. Évitez le chapter unique « Divers ». Pour un book Onboarding développeur, des chapters typiques sont : Accès et outils, Setup local, Workflow Git interne, Premier déploiement, Astreinte semaine 1.

BookStack permet de réordonner les chapters par glisser-déposer. Profitez-en : l’ordre raconte l’histoire d’apprentissage. Mettez les chapters d’urgence (sécurité, accès) en premier, les chapters de spécialisation à la fin.

Étape 5 — Convention de nommage stricte des pages

Sans convention, votre wiki devient un cimetière en 6 mois. Imposez trois règles :

1. Verbe d'action en tête : "Créer un VPS Hetzner", pas "VPS Hetzner"
2. Pas d'acronyme interne sans glose : "Pipeline ETL (Extract Transform Load)"
3. Pas de date dans le titre : la date va dans la métadonnée "Last updated"

Faites tourner cette règle 3 mois avant d’ouvrir BookStack à toute l’équipe. Un wiki mal nommé décourage la recherche : à Bamako comme à Dakar, les collaborateurs préfèrent demander à un collègue plutôt que de fouiller un wiki en désordre.

Étape 6 — Permissions par étagère, jamais par page

BookStack hérite les permissions du parent vers l’enfant. Configurez les rôles au niveau des étagères : Tout le monde en lecture, Équipe Produit en édition pour Produit & Tech, Direction en édition pour Finance & Compta. Ne descendez à la granularité du chapter ou de la page que pour des cas exceptionnels (fiches de paie, mots de passe administrateurs — qui de toute façon ne devraient pas être dans BookStack mais dans Vaultwarden).

Vérifiez après chaque création de book que les permissions héritées sont correctes via Settings > Roles. Une page confidentielle accidentellement publique est très difficile à rattraper une fois indexée.

Étape 7 — Templates de page pour uniformiser les contributions

BookStack 24.x supporte les page templates : créez 4 à 6 modèles que les contributeurs duplicquent au lieu de partir de zéro. Modèles utiles : Procédure (Pourquoi/Quand/Étapes/Vérification), Runbook incident (Symptôme/Diagnostic/Résolution/Prévention), Décision technique (Contexte/Options/Choix/Conséquences), Compte-rendu de réunion.

Activez la fonctionnalité dans Settings > Customization > Templates. Chaque template est une page normale taggée template. Lors de la création d’une nouvelle page, le rédacteur sélectionne un template dans le menu déroulant. Le gain de temps est immédiat et la cohérence visuelle s’installe sans effort.

Étape 8 — Tags transversaux pour la recherche

La hiérarchie répond à la question « où ranger ? », les tags répondent à « comment retrouver ? ». Définissez un vocabulaire contrôlé de 15 à 25 tags maximum. Exemples : statut:draft, statut:validated, statut:obsolete, zone:dakar, zone:abidjan, criticite:haute, type:procedure, type:runbook.

Imposez via la doc interne que chaque page porte au moins un tag statut: et un tag type:. Un cron mensuel qui remonte les pages sans tag suffit à maintenir la discipline.

Étape 9 — Sauvegardes et migration vers une nouvelle instance

BookStack stocke ses données dans MySQL/MariaDB et ses pièces jointes dans /var/www/bookstack/storage/uploads. Une sauvegarde quotidienne combinée résout 100 % des cas de perte. À programmer dans cron à 02:00 UTC :

mysqldump -u bookstack -p"$DB_PASS" bookstack | gzip > /backup/bs-$(date +%F).sql.gz
tar czf /backup/uploads-$(date +%F).tgz /var/www/bookstack/storage/uploads
rclone copy /backup/ remote:bookstack-backups --max-age 24h

Pour migrer vers une nouvelle instance, restaurez le dump SQL puis recopiez les uploads avant le premier démarrage. BookStack régénère seul les miniatures au fil de la navigation. Testez la restauration tous les semestres : un backup non testé est une fiction.

Pour creuser ce sujet, voyez aussi notre guide sur les headers de sécurité Caddy pour exposer BookStack en HTTPS, et notre tutoriel Cloudflare gratuit pour mettre votre wiki derrière un CDN.

Étape 10 — Cycle de revue trimestrielle des contenus

Le pire ennemi d’un wiki est l’information obsolète. Planifiez tous les trois mois une revue de contenu de 2 heures par étagère, animée par le référent métier. La revue produit trois actions : marquer les pages valides comme statut:validated, mettre à jour celles qui ont dérivé, archiver via le tag statut:obsolete les pages dépassées (plutôt que les supprimer, pour conserver l’historique).

Cette discipline simple, appliquée pendant un an, transforme BookStack en source de vérité que toute l’équipe consulte spontanément, à Dakar comme à Cotonou ou Bamako.

Étape 11 — Importer une documentation Confluence ou Notion

De nombreuses PME basculent depuis Notion (jugé trop cher en USD) ou Confluence Cloud vers BookStack self-hosted. La méthode la plus fiable : exporter chaque espace en HTML, nettoyer les feuilles de styles propriétaires, puis importer page par page via l’éditeur WYSIWYG.

Pour un volume de 200+ pages, scriptez l’import via l’API REST officielle de BookStack 24.x.

curl -X POST "https://wiki.exemple.sn/api/pages" \
  -H "Authorization: Token id:secret" \
  -H "Content-Type: application/json" \
  -d '{"chapter_id": 12, "name": "Procédure ouverture de compte", "html": "<p>...</p>"}'

Le retour HTTP 200 contient l’ID de la page créée. Bouclez sur votre liste source en respectant 1 requête par seconde pour éviter de saturer la base. Comptez 30 minutes pour migrer 500 pages depuis Notion vers BookStack avec ce pattern.

Étape 12 — Mesurer l’adoption interne

BookStack expose les statistiques de consultation par page, accessibles via Settings > Audit log. Extrayez les pages les plus consultées sur 30 jours pour identifier les sujets qui fonctionnent. Inversement, listez les pages jamais consultées : 80 % méritent d’être supprimées ou fusionnées.

Présentez chaque trimestre à la direction un tableau simple : nombre de pages totales, nombre de pages consultées au moins une fois, top 10 des pages, top 10 des contributeurs. Ce reporting de 5 minutes par mois maintient la pression positive et justifie le temps investi dans la documentation interne.

Étape 13 — Aller plus loin avec les diagrammes intégrés

BookStack 24.x intègre nativement Drawio pour les schémas. Inutile d’aller chercher un outil externe : depuis l’éditeur, cliquez sur l’icône diagramme et dessinez votre architecture directement dans la page. Le SVG est stocké dans le dump MySQL et survit à toutes les sauvegardes.

Pour les diagrammes de séquence ou les organigrammes très techniques, activez aussi Mermaid via le plugin Markdown. Vous obtenez ainsi une documentation vivante, versionnée avec votre wiki, sans dépendance externe payante en USD.

Étape 14 — Sécuriser l’accès et journaliser les actions sensibles

Activez l’authentification à deux facteurs TOTP dans Settings > Security pour tous les comptes ayant un rôle d’administration. Compatible avec Google Authenticator, Aegis, FreeOTP. Combinez avec une politique de mot de passe minimum 12 caractères. L’audit log natif trace les créations, suppressions, modifications de permissions et changements de rôle, exportable en CSV pour vos rapports de conformité.

Conservez l’audit log au moins 12 mois. Sur une PME à Dakar ou Abidjan facturant ~500 000 FCFA par mois ses prestations, l’historique d’accès devient une preuve précieuse en cas de litige avec un client ou un ancien collaborateur. Cinq minutes de configuration, des années de tranquillité.

Étape 15 — Trois pièges fréquents à éviter

Premier piège : créer une étagère par équipe. Les équipes changent, les flux métier restent. Toujours raisonner en flux. Deuxième piège : importer 2 000 pages le premier jour sans hiérarchie. Mieux vaut commencer avec 30 pages bien rangées que noyer le wiki sous des contenus orphelins. Troisième piège : oublier la formation des contributeurs. Une session d’1 heure pour expliquer la convention de nommage, l’usage des tags et le cycle de revue trimestrielle vaut tous les modèles de page du monde.

Appliquée avec rigueur sur 6 mois, cette méthode produit un wiki BookStack que toute votre PME consulte sans rechigner, à Dakar, à Cotonou comme à Bamako.