Permissions et workflow éditorial BookStack : tutoriel 2026

📍 Article principal : BookStack 2026 : guide pratique.

Sans rôles définis, votre BookStack est ouvert. Ce tutoriel détaille la configuration éditoriale validée chez plusieurs PME francophones.

Prérequis

• BookStack en production avec collections.
• Au moins 5 utilisateurs.
• Niveau : intermédiaire/avancé.
• Temps : 1-2h.

Modèle de rôles

• Admin : tout pouvoir.
• Editor : crée et update pages, pas de delete.
• Reviewer : valide draft → published.
• Author : crée pages en draft uniquement.
• Viewer : lecture seule.
• Public : pages explicitement publiques.

Étape 1 — Créer rôles

Settings → Roles → Add new role. Pour Editor :

• Display name : Editor.
• System permissions : create-all, update-all (pas delete).
• Asset permissions : Books-Update, Pages-Create, Pages-Update.

Étape 2 — Permissions par shelf

Sur shelf « Engineering » → Permissions → custom :

• Editor : View, Create, Update.
• Reviewer : View, Update (uniquement field status).
• Author : View, Create.
• Viewer : View.

Étape 3 — Permissions par book

Permissions héritent du shelf, override possible book par book pour confidentialité.

Étape 4 — Permissions par page

Page critique (ex : access-codes, secrets) : permissions strictes par utilisateur explicite.

Étape 5 — Workflow draft → published

BookStack n’a pas workflow natif draft/published comme Directus. Workaround :

• Tag « draft » sur pages en cours.
• Tag « review-requested ».
• Tag « published ».
• Reviewer scan tags review-requested, valide, change tag.

Étape 6 — Notifications email

Settings → Notifications → email on page update. Reviewers reçoivent notif quand Author edit.

Étape 7 — Audit log

Settings → Audit Log. Toutes actions tracées : qui a edit, créé, supprimé. Conservation 90 jours par défaut.

Étape 8 — Public pages

Pour exposer doc support client publiquement :

• Settings → Roles → Public role → permissions sur shelf « Public Documentation ».
• View only.
• Settings → URL & Privacy → Allow public access.

Pages publiques accessibles sans login. URL https://docs.votre-entreprise.com/books/....

Étape 9 — Anonymous read mode

Pour FAQ entièrement publique : Public role gain View sur tout. URL home affichable sans login.

Étape 10 — Test scénario complet

1. Author crée page (tag draft).
2. Author tag review-requested.
3. Reviewer reçoit notif email.
4. Reviewer relit, change tag published.
5. Page apparaît dans search public si shelf public.

Erreurs fréquentes

Sur le terrain au Sénégal et en Afrique de l’Ouest

Trois précisions. Workflow journaliste/rédacteur : Author = journaliste, Reviewer = chef édition. Tag-based workflow simple. Multi-clients ESN : un shelf par client, role Vendor avec view limité. Compliance : audit log Loki retention 1 an.

Tutoriels frères

• Déployer BookStack
• SSO Authentik

FAQ

Combien rôles max ? Pas limite. 5-10 typique.

Permissions héritées ? Shelf → Book → Chapter → Page. Override per niveau.

SSO + rôles ? Map groupe Authentik → role BookStack via OIDC_USER_TO_GROUPS.

Approbations multi-niveaux ? Workflow custom via tags + API.

Audit conformité ? Audit log + Loki = trace complète.

Dans la continuité

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

Étape 1 — Comprendre la hiérarchie BookStack

Avant de définir des permissions, il faut visualiser la structure : un Shelf (étagère) regroupe plusieurs Books, chaque Book contient des Chapters et des Pages. Les permissions s’héritent du haut vers le bas par défaut, mais peuvent être surchargées à chaque niveau. Pour une SCI ou une agence digitale basée à Dakar avec dix collaborateurs, la modélisation gagne à coller à la structure RH : un shelf par département, un book par projet client.

Shelf "Clients SaaS"
  ├─ Book "Banque Atlantique - Refonte"
  │   ├─ Chapter "Spec API"
  │   └─ Chapter "Onboarding KYC"
  └─ Book "Sonatel - Portail B2B"

Cette arborescence se construit en 5 minutes via l’interface Admin. Conservez des slugs courts et explicites, ils apparaissent dans les URLs internes et facilitent les recherches au clavier.

Étape 2 — Créer les rôles métier de base

BookStack 2026 livre les rôles Admin, Editor, Viewer par défaut. Pour un workflow éditorial professionnel, ajoutez trois rôles supplémentaires : Author (rédacteur, peut créer mais pas publier), Reviewer (peut commenter et approuver), Publisher (peut publier et archiver).

# Settings > Users > Roles > Create new role
Nom: Author
Permissions par défaut:
  - Create own pages: oui
  - Edit own pages: oui
  - Delete own pages: non
  - Create own books: non

Le principe directeur : un Author voit uniquement les pages dont il est propriétaire et peut les modifier, mais ne peut pas publier publiquement ni supprimer. Cette séparation responsabilise l’auteur sur son contenu sans risquer la suppression accidentelle d’une page validée par d’autres.

Étape 3 — Permissions granulaires par étagère

L’étape clé : surcharger les permissions au niveau d’un shelf spécifique pour qu’un client n’accède qu’à son propre shelf. Allez dans le shelf > Permissions > Use custom permissions for this shelf, puis cochez explicitement les rôles autorisés en View, Update, Delete.

# Shelf "Banque Atlantique"
View:    Admin, Author, Reviewer, Publisher, Client-BA
Create:  Admin, Author, Publisher
Update:  Admin, Publisher
Delete:  Admin
# Décocher tous les autres rôles, y compris Editor générique

Activez en bas la case Apply these permissions to children pour propager aux books, chapters et pages internes. Un oubli ici expose des contenus sensibles à toute l’équipe : faites un test immédiat en vous connectant avec un compte de chaque rôle pour vérifier ce qui est visible ou non.

Étape 4 — Workflow brouillon-révision-publication par labels

BookStack n’a pas de système de workflow natif type Confluence, mais on simule un workflow propre via Tags. Ajoutez systématiquement à chaque page un tag status avec valeurs draft, review, approved, published, archived.

# Sur une page > Edit > Tags
status: draft   # auteur écrit
status: review  # auteur termine, demande revue
status: approved # reviewer valide
status: published # publisher rend public
status: archived  # contenu obsolète conservé

Filtrez ensuite via la recherche BookStack : [status=review] liste toutes les pages en attente de revue. Un reviewer commence sa journée par cette URL en bookmark et traite la file. C’est un workflow pragmatique, sans plugin, fonctionnel dès le premier jour.

Étape 5 — Activer l’audit log et le surveiller

Depuis BookStack 2024, l’audit log natif trace toutes les actions sensibles : création, modification, suppression, changement de permissions, login. Activé par défaut, il garde 90 jours d’historique. Vérifiez dans Settings > Maintenance > Audit Log Settings que la rétention correspond à votre politique de conformité interne.

# Filtrer les suppressions des 7 derniers jours
URL: /settings/audit?event=page_delete&date_from=2026-04-28
# Exporter en CSV pour archivage hors-site
curl -u admin@x:token https://docs.votredomaine.com/api/audit-log?event=permissions_update > audit.json

Plantez un cron mensuel qui exporte le log vers un bucket S3 chiffré. En cas d’incident de sécurité ou d’audit ISO 27001, vous présentez l’historique complet sans dépendre du serveur de production éventuellement compromis.

Étape 6 — Notifications Slack ou Mattermost à chaque publication

Pour qu’une équipe distribuée entre Dakar, Abidjan et Cotonou reste alignée, branchez un webhook Slack ou Mattermost qui poste un message à chaque page passée à status=published. BookStack expose des webhooks natifs dans Settings > Webhooks depuis la version 24.10.

Settings > Webhooks > Create
Nom: Slack #docs-publi
URL: https://hooks.slack.com/services/T0xxx/Bxxxx/xxxxx
Événements:
  - page_create
  - page_update
Méthode: POST

Le payload JSON envoyé contient le titre, l’URL, l’auteur. Côté Slack, configurez un format de message custom via Workflow Builder pour afficher uniquement les champs pertinents au lieu du JSON brut. Comptez 15 minutes pour une intégration complète testée en bout en bout.

Étape 7 — Sauvegarder BookStack proprement

BookStack stocke trois choses : la base MySQL/MariaDB (structure et contenu), les uploads dans storage/uploads (images, PJ), le fichier .env (clés et configuration). Une sauvegarde correcte couvre les trois.

#!/bin/bash
TS=$(date +%Y%m%d-%H%M)
mysqldump -u bookstack -p$DB_PASS bookstack | gzip > /backup/bookstack-$TS.sql.gz
tar czf /backup/uploads-$TS.tgz /var/www/bookstack/storage/uploads
cp /var/www/bookstack/.env /backup/env-$TS
restic backup /backup --tag bookstack-daily

Pour un wiki d’équipe avec 5 000 pages et 2 Go d’uploads, comptez 30 secondes pour le dump et 90 secondes pour le tar. Planifiez via cron à 02:30 UTC, complétez par une vérification d’intégrité hebdomadaire avec restic check.

Étape 8 — Recherche full-text et SEO interne

BookStack utilise la recherche MyISAM full-text de MySQL, performante sur des wikis jusqu’à 50 000 pages sans configuration. Au-delà, branchez un MeiliSearch externe via le hook approprié pour gagner en pertinence et tolérance aux fautes de frappe françaises.

# Settings > Customization > Custom Head Content
<script>
  // Améliore l'UX en mettant en surbrillance les mots cherchés
  document.addEventListener('DOMContentLoaded', () => {
    const q = new URLSearchParams(location.search).get('term');
    if (q) document.querySelectorAll('main p').forEach(p => {
      p.innerHTML = p.innerHTML.replace(new RegExp(q,'gi'), m => `<mark>${m}</mark>`);
    });
  });
</script>

Côté SEO interne, ajoutez systématiquement 2 à 3 liens entre pages connexes. Le menu de navigation latéral aide, mais ce sont les liens contextuels dans le corps qui réduisent réellement le nombre de tickets support en interne.

Étape 9 — Authentification SSO via Azure Entra ID ou Google Workspace

Pour une équipe de plus de 5 personnes, le SSO élimine la gestion manuelle des mots de passe et centralise la révocation d’accès au moment du départ d’un collaborateur. BookStack supporte SAML 2.0 et OIDC nativement.

# .env extrait pour OIDC Azure Entra ID
AUTH_METHOD=oidc
OIDC_NAME=Azure
OIDC_DISPLAY_NAME_CLAIMS=name
OIDC_CLIENT_ID=
OIDC_CLIENT_SECRET=
OIDC_ISSUER=https://login.microsoftonline.com//v2.0
OIDC_ISSUER_DISCOVER=true
OIDC_USER_TO_GROUPS=true

L’option OIDC_USER_TO_GROUPS mappe automatiquement les groupes Entra ID vers les rôles BookStack par nom. Créez les rôles BookStack avec exactement les mêmes noms que vos groupes AD pour que le mapping fonctionne sans configuration supplémentaire.

Étape 10 — Diagnostic des permissions en panne

Le bug typique : un utilisateur ne voit pas une page qu’il devrait voir. La cause habituelle est une régénération de permissions non exécutée après un changement structurel (déplacement de page, changement de rôle).

# Régénérer toutes les permissions cumulées
php artisan bookstack:regenerate-permissions
# Vérifier les rôles d'un utilisateur précis
php artisan tinker
>>> User::where('email','user@ex.com')->first()->roles

L’opération prend 5 à 30 secondes selon la taille du wiki. Planifiez-la dans un cron hebdomadaire dominical pour absorber les régressions silencieuses, et systématiquement après une migration de version BookStack majeure.

Étape 11 — Coût et alternatives

BookStack est gratuit et open source (MIT). Hébergé sur un VPS Hetzner CX11 à 4,75 EUR/mois soit ≈ 3 116 FCFA, il accueille confortablement 30 utilisateurs actifs. Comparé à Confluence Cloud (5,75 USD/utilisateur/mois soit ≈ 3 770 FCFA × 30 = 113 100 FCFA/mois), l’auto-hébergement divise la facture par 35 sans perte fonctionnelle pour 90 % des cas d’usage d’une PME ouest-africaine.

Dans la continuité sur la gestion documentaire, voir notre comparatif des wikis d’équipe et notre guide SSO Azure Entra ID.

Étape 12 — Modèles de pages réutilisables (Page Templates)

Pour une équipe qui produit beaucoup de documents structurés (compte-rendu de réunion, fiche client, post-mortem incident), les Page Templates de BookStack évitent les copier-coller hasardeux. Créez une page modèle, marquez-la comme template depuis Edit > More > Mark as Template, elle devient sélectionnable au moment de créer une nouvelle page.

Modèle "Post-mortem incident"
## Contexte
[Date, durée, services impactés]
## Chronologie
- HH:MM — événement
## Cause racine
## Actions correctives
- [ ] Court terme
- [ ] Long terme
## Leçons retenues

Le bénéfice se voit dès le troisième post-mortem : la qualité de la rétrospective remonte parce que personne n’oublie une rubrique. Sur un an, l’équipe accumule un corpus exploitable pour identifier les causes récurrentes d’incidents.

Étape 13 — Migration depuis Notion ou Confluence vers BookStack

Pour un client qui veut quitter Notion ou Confluence, BookStack accepte l’import HTML ou Markdown au niveau de la page. La méthode pragmatique : exporter Notion en Markdown ou Confluence en HTML, puis utiliser l’API BookStack pour créer en boucle les pages dans la bonne arborescence.

for f in export-notion/*.md; do
  curl -X POST https://docs.votredomaine.com/api/pages     -H "Authorization: Token $TOKEN_ID:$TOKEN_SECRET"     -H "Content-Type: application/json"     -d "{"book_id":12,"name":"$(basename $f .md)","markdown":"$(cat $f | jq -Rs .)"}"
done

Comptez une demi-journée pour 200 pages bien structurées, deux jours pour 1 000 pages avec relectures de mise en forme. Les images Notion sont à télécharger séparément et ré-uploader via l’endpoint /api/image-gallery avant de fixer les URLs dans le Markdown.