Concepts
Apprenez les bases de GitBook afin de pouvoir créer et publier une documentation remarquable pour vos utilisateurs
Organisation du contenu
Espace
Un espace est un projet qui vous permet de travailler sur une collection de pages liées entre elles. Dans un espace, vous pouvez rédiger du contenu, organiser vos pages avec des groupes et des sous-pages, installer des intégrations, et bien plus encore.
Lorsque vous souhaitez publier un espace, vous pouvez le faire en l’ajoutant à un site de documentation. Vous pouvez ajouter autant d’espaces que vous le souhaitez à un site de documentation. Ainsi, lorsque vous développez votre contenu, vous pouvez créer des espaces distincts pour la documentation de votre produit, la référence API, le journal des modifications, le centre d’aide et tout autre élément que vous souhaitez inclure dans votre documentation — puis les publier tous sur un seul site de documentation.
Vous pouvez également vouloir créer des versions traduites de votre documentation principale, ou des documentations séparées pour différentes versions de votre produit. Chacune disposera également de son propre espace et pourra être ajoutée à votre site de documentation unique afin que les utilisateurs puissent la consulter.
Collection
Les collections fonctionnent comme des dossiers dans l’application GitBook, vous permettant de regrouper des espaces pour faciliter l’organisation et le stockage de votre contenu.
En plus de vous aider à organiser le contenu, les collections facilitent également la gestion des autorisations au niveau du contenu à grande échelle. Vous pouvez remplacer les autorisations au niveau de l’organisation sur plusieurs espaces en les ajoutant à une collection et en définissant des autorisations pour l’ensemble de la collection.
Site de documentation
Vous pouvez publier votre contenu sous forme de site de documentation. Vos docs seront publiées et mises à la disposition de votre public cible sous la forme d’un site web que vous pouvez personnaliser avec votre propre identité visuelle, vos analyses et votre domaine personnalisé.
Vous pouvez créer autant de sites de documentation que vous le souhaitez. Ils sont tous listés dans la barre latérale et dans la section Sites de documentation de l’application, où vous pouvez modifier les paramètres et les options de personnalisation. Vous pouvez gérer tous les paramètres et options de votre site de documentation dans l’application GitBook.
Le contenu de votre site provient des espaces de votre organisation GitBook. Lorsque vous créez un nouveau site de documentation, vous pouvez créer un nouvel espace ou en associer un existant. Un site de documentation peut contenir un seul espace, ou plusieurs espaces contenant différents contenus — y compris des traductions et des versions antérieures du produit.
Modification du contenu
L’éditeur visuel de GitBook vous permet d’utiliser une interface de type WYSIWYG (ce que vous voyez est ce que vous obtenez) pour ajouter du contenu à un espace.
Pages
Une page est l’endroit où vous ajoutez, modifiez et intégrez du contenu. Les pages se trouvent toujours à l’intérieur d’un espace, et vous pouvez ajouter autant de pages que vous le souhaitez à un espace.
Les pages de votre espace apparaissent dans la table des matières sur la gauche de l’éditeur. Ici, vous pouvez ajouter de nouvelles pages, créer des groupes de pages et imbriquer des pages dans d’autres pages pour créer des sous-pages.
Vous ne voyez pas comment modifier ou ajouter une page ?
Si votre site est publié, vous devrez créer une demande de modification avant de pouvoir apporter des changements au contenu d’un espace. Lisez ci-dessous à propos des demandes de modification.
Blocs
GitBook est un éditeur basé sur des blocs. Cela signifie que vous pouvez ajouter différents types de blocs à votre page — du texte et des images standards aux blocs interactifs plus avancés. Vos pages peuvent inclure toute combinaison de blocs que vous souhaitez, et il n’y a aucune limite au nombre de blocs que vous pouvez avoir sur une page.
L’édition basée sur des blocs facilite la réorganisation de votre contenu par glisser-déposer, ou l’ajout de nouveaux blocs au milieu du contenu existant. Vous pouvez créer de nouveaux blocs à l’aide de l’interface de l’éditeur, ou créer et mettre en forme des blocs à l’aide de Markdown.
Découvrez tous les blocs que vous pouvez utiliser dans GitBook dans la section Blocs.
Édition Markdown
L’éditeur de GitBook vous permet de créer et de mettre en forme des blocs de contenu à l’aide de Markdown.
Markdown est une syntaxe de balisage populaire, largement reconnue pour sa simplicité. GitBook le prend en charge comme un moyen pratique au clavier d’écrire du texte riche et structuré — tous les blocs de GitBook peuvent être rédigés à l’aide de la syntaxe Markdown.
Vous pouvez en savoir plus sur Markdown en visitant CommonMark.
Synchronisation Git
Git Sync permet aux équipes de synchroniser des dépôts GitHub ou GitLab avec GitBook et de transformer des fichiers Markdown en docs attrayantes et faciles à utiliser. Une fois configuré, il maintient la synchronisation de tout votre contenu entre l’application GitBook et votre base de code.
Git Sync est bidirectionnel, donc les changements que vous apportez dans l’éditeur visuel de GitBook sont synchronisés automatiquement — tout comme les commits effectués sur GitHub ou GitLab. Cela permet aux développeurs de valider directement depuis GitHub ou GitLab tandis que les autres membres de l’équipe modifient et laissent des retours sur les changements directement dans GitBook.
Git Sync débloque également de nombreux autres flux de travail utiles dans vos docs GitBook, comme les modifications par lot, le linting, et bien plus encore. En savoir plus dans notre section Git Sync.
Le flux d’édition
Demandes de modification
Une demande de modification est une branche de votre contenu principal que vous pouvez utiliser pour effectuer des modifications simultanées tout en conservant votre historique de versions. Cela sera familier à toute personne qui utilise les pull requests dans GitHub ou les merge requests dans GitLab.
Si vous souhaitez modifier le contenu de votre site de documentation publié, vous devrez d’abord ouvrir une demande de modification dans votre espace.
Dans une demande de modification, vous pouvez ajouter, modifier et supprimer du contenu dans un espace, puis demander une revue à votre équipe et fusionner vos changements dans votre contenu principal afin de mettre à jour votre site de documentation publié.
La création de branches en bref
L’ouverture d’une demande de modification crée une copie de votre contenu à ce moment précis, parfois appelée « branche ». Les modifications que vous apportez n’apparaîtront pas dans votre contenu principal tant que vous n’aurez pas choisi de fusionner votre demande de modification.
L’avantage des branches est que vos coéquipiers peuvent créer, modifier et fusionner leurs propres demandes de modification en même temps que vous, sans se marcher sur les pieds. Et si quelqu’un modifie le même contenu que vous, GitBook vous guidera pour résoudre les conflits avant la fusion.
Revues
Les revues encouragent la supervision et contribuent à améliorer la qualité et la précision de votre documentation.
Vous pouvez demander une revue de votre demande de modification avant de la fusionner et de mettre les changements en ligne sur votre site de documentation. Ajouter un titre et une description à votre demande de modification donne à vos relecteurs un peu de contexte.
Les relecteurs peuvent consulter le diff de votre demande de modification, qui met en évidence tout ce qui est nouveau, modifié ou supprimé. Ils peuvent également laisser des commentaires directement sur la page grâce à la fonctionnalité de commentaires intégrée — puis approuver votre demande de modification ou demander d’autres changements.
Fusion
La fusion d’une demande de modification ajoutera tout le contenu de votre demande de modification à la branche principale du contenu — et ces changements seront également mis en ligne sur votre site de documentation.
Lorsque vous fusionnez votre demande de modification, cela crée également une nouvelle version dans l’historique des versions de l’espace.
Publication de la documentation
Lorsque vous publiez votre contenu en tant que site de documentation, vous pouvez ajouter du contenu supplémentaire à votre site, changer le public cible et personnaliser son apparence, son ergonomie et d’autres paramètres.
Structurer votre site de documentation
Si vous souhaitez ajouter du contenu supplémentaire à votre site, deux options s’offrent à vous, chacune conçue pour des cas d’usage différents : les sections du site et les variantes.
Section du site
Les sections du site sont conçues pour vous permettre d’ajouter plusieurs types de documentation différents à un seul site de documentation. Par exemple, vous pouvez utiliser un seul site de documentation pour héberger la documentation de votre produit, la référence API, le centre d’aide et le journal des modifications — comme nous le faisons sur ce site de documentation.
Lorsque vous ajoutez de nouvelles sections au site, vous construisez la barre de navigation en haut de votre site, chaque section ayant sa propre entrée dans la barre. Vous pouvez également regrouper des sections du site pour créer un menu déroulant dans votre barre de navigation — idéal pour ajouter une hiérarchie à vos sections du site.
Variante
Les variantes sont conçues pour vous permettre d’ajouter plusieurs versions de la même documentation à un seul site de documentation. Par exemple, vous pouvez vouloir localiser toute votre documentation en plusieurs langues, ou documenter les versions antérieures de votre produit pour les utilisateurs qui n’ont pas effectué la mise à jour.
Vos utilisateurs finaux peuvent passer d’une variante à l’autre sur votre site de documentation à l’aide du sélecteur de langue ou du sélecteur de variante en haut de la table des matières, sur le côté gauche de votre site.
Public du site
Vous pouvez choisir qui verra votre documentation lorsque vous la publierez. Par défaut, les nouveaux sites sont publiés publiquement et indexés par les moteurs de recherche.
Cependant, si vous souhaitez avoir plus de contrôle sur les personnes pouvant accéder à votre site, vous pouvez choisir de limiter l’audience en utilisant des liens de partage ou l’accès authentifié.
Avec les liens de partage, vous pouvez partager votre contenu en privé avec des clients ou des partenaires sans avoir à les inviter dans votre organisation, en créant un lien privé et en le partageant directement avec eux. Toute personne disposant du lien peut accéder à votre site.
Si vous souhaitez encore plus de contrôle, l’accès authentifié vous permet de publier votre contenu tout en exigeant une authentification de la part de tout visiteur souhaitant le consulter. Lorsqu’il est activé, GitBook laisse votre fournisseur d’authentification gérer qui a accès au contenu. C’est idéal pour du contenu privé ou pour publier une base de connaissances interne qui ne devrait être accessible qu’aux membres de votre équipe.
Vous pouvez également contrôler qui voit des pages ou des blocs individuels à l’aide d’une fonctionnalité appelée contenu adaptatif. Une fois configurée, elle affiche ou masque le contenu en fonction des attributs utilisateur que vous définissez. En savoir plus dans les pages de contenu adaptatif.
Personnalisation du site
GitBook inclut des options de personnalisation intégrées pour les sites de documentation, vous aidant à harmoniser l’apparence et le ressenti de votre documentation avec votre produit ou votre marque.
Même si vous n’appliquez aucune personnalisation, vos docs seront très belles telles quelles. Mais vous avez la possibilité de personnaliser les logos, les icônes et les couleurs, d’ajouter des polices personnalisées ou de choisir parmi certains thèmes intégrés qui aident vos docs à être aussi belles que votre produit.
Optimisations SEO et IA
La documentation publiée dans GitBook est automatiquement optimisée pour la recherche (SEO) et pour les systèmes d’IA comme ChatGPT, Claude et Google AI Overview (GEO). Ces éléments sont gérés en arrière-plan, donc tout ce que vous avez à faire est de rédiger du contenu incluant les mots-clés et termes que vous souhaitez cibler.
Les pages récupèrent les métadonnées à partir du titre et de la description de chaque page, et votre contenu est mis en forme pour être responsive. GitBook crée automatiquement un sitemap basé sur votre table des matières, et les pages sont mises en cache et diffusées via notre CDN mondial pour améliorer les performances. Tout cela aide votre documentation à se classer en bonne position dans les moteurs de recherche.
De même, GitBook optimise aussi pour les outils d’IA en suivant toutes les normes du secteur à mesure qu’elles évoluent rapidement.
GitBook crée automatiquement des versions .md de chaque page, ce qui facilite leur analyse par les grands modèles de langage (LLM). Nous exposons également automatiquement un serveur Model Context Protocol (MCP) pour chaque site publié, offrant aux outils d’IA une manière structurée de découvrir et de récupérer vos docs comme ressources — sans aucun scraping requis. De plus, votre site génère aussi llms.txt et llms-full.txt conçu pour l’ingestion par l’IA.
Gestion d’équipe
Organisation
Une organisation GitBook contient tout le contenu et tous les sites de documentation d’une entreprise. Avec votre compte unique, vous pouvez être membre d’une ou de plusieurs organisations et passer de l’une à l’autre à l’aide du menu déroulant en haut à gauche de l’application GitBook.
Membres
Les membres sont des utilisateurs individuels au sein de votre organisation. Vous pouvez avoir autant de membres que vous le souhaitez dans une organisation, chacun avec des autorisations adaptées à ses besoins d’accès spécifiques.
Autorisations
Les autorisations vous permettent de décider du niveau d’accès des membres de votre organisation. Lorsqu’un membre rejoint votre organisation, vous lui attribuez un rôle — tel qu’Éditeur ou Lecteur. Ces rôles définissent leurs autorisations pour tout le contenu de votre organisation. Mais vous pouvez également remplacer ces autorisations au niveau du contenu. Par exemple :
Vous pouvez donner à une personne ayant le rôle Lecteur un accès de modification à un contenu particulier
Vous pouvez limiter l’accès à certains contenus confidentiels ou privés et n’accorder l’accès qu’à certains membres de votre organisation.
En savoir plus sur la page Autorisations et héritage.
Mis à jour
Ce contenu vous a-t-il été utile ?