# La doc

# Concepts de Base de l'outil BookStack

#### Principes : les éléments de base

BookStack, "Pile de Livre" en Anglais, est un outil qui organise nos informations à l'image d'une bibliothèque physique.

- On dispose d'autant "d'[**Étagères**](https://seg2026.aubaygues.fr/shelves "Étagères")" que l'on veut, dans lesquelles
- on range autant de "[**Livres**](https://seg2026.aubaygues.fr/books "Livres")" que l'on veut,
- qui contiennent autant de "**Pages**" simples que l'on veut,
- et on peut regrouper ces pages en "**Chapitres**"

La seule particularité avec une bibliothèque physique est qu'ici un livre peut être rangé, référencé dans plusieurs étagères, (ce qui n'est ni le cas de chapitres, ni le cas des pages)

C'est presque tout ce qu'il faut savoir pour commencer à utiliser l'outil.

Les boutons [![image.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/image-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/image-png.png) renvoient respectivement aux *Catalogues* des étagères et celui des livres déjà créés.

#### Principes : Les autorisations et le Collaboratif !

La question que l'on se pose toujours, c'est qui peut *voir (lire), commenter, modifier, créer et supprimer* les documents que l'on ajoute.

##### Sur chaque éléments (pages, chapitres, livre ou étagère) BookStack offre la possibilité de cocher les types d'autorisation spécifiques que le propriétaire (l'auteur) souhaite lui donner :

[![BookStack-permissions-pages.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstack-permissions-pages-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstack-permissions-pages-png.png)

*Il est donc possible de faire des éléments complètement "privés" que seul le créateur (et l'admin) peuvent voir. Cela peut-être commode pour des brouillons de travail qu'on ne veut pas encore partager en cours d'élaboration par exemple ; il est aussi possible de permettre la lecture seule mais pas la modification par les autres de ce type de document.*

> Comme l'organisation, la hiérarchie, des éléments est `<em><span style="background-color:rgb(191,237,210);">Étagère <- Livre <- Chapitre <- Page</span></em>`, BookStack offre un mécanisme d'héritage (transfert) par défaut des droits du *parent* (contenant) aux *enfants* (contenus).Mais ce mécanisme d'attribution des droits d'accès n'est jamais prioritaire sur les droits définis directement sur l'élément.  
> Par exemple on peut créer un livre partagé avec tous, dans lequel certaines pages ou chapitres sont partagés avec tous par héritage des droits et seulement certaines pages ou chapitres sont rendus invisibles (privés) en cochant les droits plus spécifiques que l'auteur veut leur attribuer.

##### BookStack propose de travailler avec avec des "*Rôles*" qui sont attribués à chaque utilisateur. 

##### Commençons par les Utilisateurs.

Il y a par défaut 4 type de rôles : **Administrateur, Éditeur, Lecteur, Public**

<details id="bkmrk-les-diff%C3%A9rents-r%C3%B4les"><summary>Les DIfférents Rôles par défaut</summary>

<div class="item-list"><div class="item-list-row flex-container-row py-xs items-center"><div class="py-xs px-m flex-2">[Admin](https://seg2026.aubaygues.fr/settings/roles/1)  
<small>Administrator of the whole application</small></div><div class="text-right flex py-xs px-m text-muted">1 utilisateur assigné   
61 permissions</div></div><div class="item-list-row flex-container-row py-xs items-center"><div class="py-xs px-m flex-2">[Editor](https://seg2026.aubaygues.fr/settings/roles/2)  
<small>User can edit Books, Chapters &amp; Pages</small></div><div class="text-right flex py-xs px-m text-muted">7 utilisateurs assignés   
39 permissions</div></div><div class="item-list-row flex-container-row py-xs items-center"><div class="py-xs px-m flex-2">[Public](https://seg2026.aubaygues.fr/settings/roles/4)  
<small>The role given to public visitors if allowed</small></div><div class="text-right flex py-xs px-m text-muted">9 utilisateurs assignés   
9 permissions</div></div><div class="item-list-row flex-container-row py-xs items-center"><div class="py-xs px-m flex-2">[Viewer](https://seg2026.aubaygues.fr/settings/roles/3)  
<small>User can view books &amp; their content behind authentication</small></div><div class="text-right flex py-xs px-m text-muted">8 utilisateurs assignés   
9 permissions</div></div></div></details>##### Le **<span style="text-decoration:underline;">Public</span>**, c'est par défaut un visiteur qui n'a pas de compte sur le site et donc qui ne peut voir que les documents dont l'accès à été donné au public, qui n'a que le droit de '<span style="text-decoration:underline;">voir</span>' - lecteur

*Par défaut, tous les utilisateurs connectés avec leur compte sont logiquement dans cette catégorie aussi.   
Il est donc possible, par exemple, d'attribuer à toute une étagère le fait d'être ou ne pas être visible par le public qui consulte le site.*

##### Les **<span style="text-decoration:underline;">Lecteurs</span>** peuvent <span style="text-decoration:underline;">voir</span> les documents et <span style="text-decoration:underline;">écrire</span> des <span style="text-decoration:underline;">commentaires,</span> en fonction des autorisations précisées le cas échéant sur l'élément lui-même. 

##### Les **<span style="text-decoration:underline;">Éditeurs</span>**, en plus de voir les documents, ont la possibilité de <span style="text-decoration:underline;">créer, d'éditer</span>, des nouveaux éléments et de modifier des éléments existants, et dans une certaine mesure de les ***supprimer***.

##### *Il faut donc, comme toujours, être précautionneux et bien sûr de ce que l'on fait au moment de valider la suppression d'un élément* !

La fonction ÉDITEUR est la fonction de base la plus intéressante pour l'objet de ce site : partager des informations, des documents, écrire en collaboration des textes, commenter le travail en cours, etc*.*

##### La fonction **<span style="text-decoration:underline;">Administrateur</span>** est celle de faire vivre, organiser, créer les comptes, etc. 

Pour le début, il y en a un, mais il serait bon qu'il y ait entre 2 et 3 personnes qui découvre en profondeur l'outil pour que Nicolas de soit pas seul dans cette fonction, pour des raisons de sécurité, pérennité et ... démocratie !

# La navigation dans le site

BookStack ne propose pas comme la plupart des sites un menu/sous-menus en haut de la fenêtre de navigation .  
La navigation est assurée en parcourant les Étagères, le Livres et pour cela BookStack affiche 3 types de zone d'informations :

<div drawio-diagram="39"><img src="http://msi-01.local:19220/uploads/images/drawio/2025-08/drawing-1-1752743176-png.png" alt="drawing-1-1752743176-png.png"/></div>

*Notez qu'en fonction de la taille de la fenêtre ou du facteur de zoom, ces zones e déplace ou sont mises en onglets :*

<table id="bkmrk--2" style="border-collapse:collapse;width:100%;"><colgroup><col style="width:50%;"></col><col style="width:50%;"></col></colgroup><tbody><tr><td>[![bookstach-adffichage-1_colonne.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstach-adffichage-1-colonne-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstach-adffichage-1-colonne-png.png)</td><td>[![bookstach-adffichage-onglets.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstach-adffichage-onglets-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstach-adffichage-onglets-png.png)</td></tr></tbody></table>

##### **Navigation :**

- ***Navigation dans la Page*** : Liste des paragraphes, lien etc
- ***Navigation dans le livre***  **:** Liste des pages et chapitres du livres

Notez aussi l'affichage du chemin de navigation en haut du document, ou tous les éléments sont des liens actifs

<div drawio-diagram="45"><img src="http://msi-01.local:19220/uploads/images/drawio/2025-08/drawing-1-1752745731-png.png" alt="drawing-1-1752745731-png.png"/></div>

Notez aussi la zone de recherche dans les mots clés et tout le texte (recherche plein-texte) !

- Navigation entre les Pages d'un livre : Notez le bas le chaque page affichée, les boutons "**Précédent/Suivant**", "**Ajouter un commentaire**" et **l'ajout puis l'affichage de commentaires**
    
    ##### [![bookstack-navigation_pied2page.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstack-navigation-pied2page-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstack-navigation-pied2page-png.png)

##### **Actions et Détails de l'élément :**

- ***Détails*** : Informations concernant cet élément
- ***Actions*** : Les <span style="text-decoration:underline;">**ACTIONS**</span> autorisées sur cet élément ; au maximum : 
    - **Nouveau/Nouvelle** {page, chapitre, livre, étagère}
    - **Éditer** : entrer dans le mode modification.   
        ⚠️<span style="color:rgb(149,165,166);"> ***<span style="color:rgb(126,140,141);">BookStack étant un outil collaboratif, toute modification enregistrée le sera pour tout le monde</span>***</span>.   
        Ceci dit, le mécanisme de gestion des Révisions intégré permet de garde l'historique des révisions et de revenir à une version précédente le cas échéant.
    - **Copier** : l'Action copier ne fonctionne pas tout à fait comme le Copier/Coller du clavier. En fait, il duplique l'élément (page, chapitre, livre ou étagère) à l'emplacement ou il se trouve. Libre à l'auteur de la copie de le renommer, déplacer, etc.
    - **Déplacer** : La suite logique de la copie si nécessaire ou au besoin pour réorganiser.   
        Noter qu'on peut aussi déplacer certains éléments comme les pages et chapitre en les faisant "glisser" à leur nouvelle place à l'intérieur d'un livre.
    - Révisions : afficher, puis agir éventuellement sur l'historique d'édition du document  
        [![booksctak-actions_révision.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/booksctak-actions-revision-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/booksctak-actions-revision-png.png)
    - **Supprimer** : Supprime l'élément sélectionné ou affiché.  
        ⚠️ ***<span style="color:rgb(186,55,42);">L'action de supprimer est définitive !  
          
        </span>***
- ***Actions complémentaires*** : 
    - - **Suivre :** Suivre les modifications, commentaires qui seraient fait sur cet élément. Très utile pour suivre l'avancée d'un travail. Cette fonction n'est pas disponible pour tous les éléments
        - **Favoris** : Ajout l'élément à la liste de ses favoris pour un accès rapide et personnalisé
        - **Exporter** : Dans sa conception Open Source, BookStack favorise l'exportation simple de tous les documents créés et donc propose des formats d'export courant comme pdf, doc, etc.  
            [![image.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/SOTimage-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/SOTimage-png.png)

# Les Fonctions de l'éditeur

##### **Fonctions d'édition**

Sauf à être ressorti hier de la grotte du banquier après y être entré au néolithique, tout le monde aujourd'hui connait les principes de base d'une éditeur de texte, surtout lorsqu'il est réduit à sa plus simple expression comme ici.

Un rappel tout de même : comme dans beaucoup de traitement de texte, la touche <span style="text-decoration:underline;">*Entrée*</span> (Return) créer une nouveau paragraphe, tandis que *<span style="text-decoration:underline;">Contrôle-Entrée</span>* (Ctrl-Return) passe à la ligne dans le même paragraphe.   
(ici, un crtl-Return) ce qui est très utile pour gérer les espacements entre lignes et paragraphes, notamment.

BookStack offre peu de fonctions d'édition et c'est un de ses atouts : du coup, tous les textes rédigés ou mis en forme ici ont tous un "air de famille" quel qu'en soit le rédacteur, ce qui participe énormément à l'agrément de lecture.

Le mieux est d'aller dans une page de test du '[Bac-à-sable](https://seg2026.aubaygues.fr/books/entrainez-vous-ici "Entrainez-vous ici !")' et de tester toutes les options de mise en forme, les unes après les autres.

Sinon, quelques explications pour les récalcitrant de l'auto-découverte :

##### **Mise en forme de texte**

<div drawio-diagram="33"><img src="http://msi-01.local:19220/uploads/images/drawio/2025-08/drawing-1-1752673736-png.png" alt="drawing-1-1752673736-png.png"/></div>

##### <s>Barré</s> | E<sup>xposant</sup> | I<sub>ndice</sub> | `Mise en bloc` | Effacer le formatage

`<em>La mise en bloc signifie que cette partie du texte se comporte comme si elle était intégrée dans un carde invisible ; à partir de ce moment là, si on clique sur n"importe quel zone du bloc, il est selectionné dans son intégralité.<br></br>C'est utile pour les commentaires, les légendes de schéma, etc</em>`

*Pour "Effacer tous les formatages de la sélection", il faut prendre soin de bien vérifier que la sélection contient les début et fin du formatage, sinon, rien ne se passera !*

##### **Mise en forme de Paragraphe**

<div drawio-diagram="34"><img src="http://msi-01.local:19220/uploads/images/drawio/2025-08/drawing-1-1752675631-png.png" alt="drawing-1-1752675631-png.png"/></div>

*Retrait à gauche | à droite sont grisés quand le texte est au bord de la la marge gauche | droite du paragraphe*

##### **Mise en forme des objets**

**La gestion des liens**

<table id="bkmrk-quand-on-s%C3%A9lectionne" style="border-collapse:collapse;"><colgroup><col style="width:50%;"></col><col style="width:50%;"></col></colgroup><tbody><tr><td>[![bookstack-editor-link.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstack-editor-link-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstack-editor-link-png.png)

</td><td>Quand on sélectionne un morceau de texte, en cliquant sur le symboles d'édition des liens :

- Si le lien est déjà créé et qu'on souhaite l'éditer, le sous menu ci à gauche apparaît (éditer | Supprimer | ouvrir le lien)
- SI le lien n'a pas encore été créé, cela ouvre directement la fenêtre ci-dessous qui permet de renseigner le lien qu'on souhaite atteindre.  
    Dans ce cas, BookStack recherche dans le site des pages ou éléments qui sont proche du texte sélectionné.   
    Pour élargir la recherche, il suffit d'effacer le texte dans la fenêtre de création du lien pour avoir accès à toutes les éléments du site

</td></tr><tr><td>[![bookstack-editor-pop_up_link_1.png](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstack-editor-pop-up-link-1-png.png)](http://msi-01.local:19220/uploads/images/gallery/2025-08/scaled-1680-/bookstack-editor-pop-up-link-1-png.png)</td><td></td></tr></tbody></table>

Editeurs

# docs exenteded Hacking BookStack

#### doc API dans le site :

[https://wiki.aubaygues.fr/api/docs](https://wiki.aubaygues.fr/api/docs)

**Reference Links**

- [API documentation of our demo instance](https://demo.bookstackapp.com/api/docs).
- [Our “BookStack API Scripts” repo containing examples](https://codeberg.org/bookstack/api-scripts).

#### Doc officelle :

[https://www.bookstackapp.com/docs](https://www.bookstackapp.com/docs "https://www.bookstackapp.com/docs")