Gérer votre site de documentation

Ce guide couvre ce que vous faites après la mise en ligne de votre site : modifier des pages, annuler une modification, décider qui peut le consulter et diagnostiquer un site qui n’a pas pris en compte votre dernier commit. Si vous n’avez pas encore publié de site, commencez par Créer votre premier site de documentation.

Connectez-vous et ouvrez votre propre site. Un widget de gestion apparaît dans le coin inférieur droit :

+----------------------+
| Your name            |
|                      |
| Select chat        > |
| Select repo        > |
| Select mode        > |
|                      |
| Settings             |
| Sign out             |
+----------------------+

Cliquez sur votre avatar ou sur Paramètres pour ouvrir le panneau des paramètres. Tout ce qui est indiqué « Paramètres » sur cette page commence ici.

Les lecteurs ne voient jamais ce widget. Les visiteurs déconnectés voient votre documentation, votre design et votre contenu, mais aucun des contrôles.

Ce que vous pouvez configurer dans les paramètres#

Section	Ce que cela contrôle	Détail
Paramètres de base	Nom de l’espace de travail et langue par défaut du site	—
Domaine personnalisé	Servir la documentation depuis une adresse qui vous appartient	Domaine personnalisé
Apparence	Thème clair, sombre ou synchronisé avec le système, et thème par défaut	Identité visuelle
Langues et traduction	Langues dans lesquelles Docsbook traduit	Traductions
Confidentialité et accès	Publique, ou protégée par mot de passe ou par votre propre fournisseur d’identité	Documentation privée
Utilisation	Solde du projet et plafonds de dépenses par source	Facturation de l’utilisation de l’IA
Widgets	Widgets de contenu affichés sur votre site	Widgets de contenu

Mettre à jour une page depuis GitHub#

Ouvrez votre dépôt sur github.com.
Ouvrez le fichier Markdown et cliquez sur l’icône en forme de crayon.
Effectuez votre modification et cliquez sur Valider les modifications.

Votre site récupère automatiquement la validation. Aucun redéploiement nécessaire.

Mettre à jour des pages depuis votre ordinateur avec git#

Utilisez cette méthode lorsque vous modifiez plusieurs fichiers à la fois et souhaitez les faire réviser ensemble.

git clone https://github.com/YOUR_USERNAME/YOUR_REPO.git
cd YOUR_REPO

Modifiez les fichiers dans votre éditeur, puis publiez-les :

git add docs/
git commit -m "Update the installation guide"
git push origin main

La suppression d’une page suit la même procédure : supprimez le fichier, validez les modifications, puis envoyez-les. La page disparaît du site et de la barre latérale.

Modifier une page sans quitter le navigateur#

Pour une petite correction, vous n’avez besoin ni de GitHub ni d’une copie locale — modifiez directement la page que vous êtes en train de lire.

Ouvrez le projet dans le chat Docsbook AI avec l’aperçu à côté (vue fractionnée).
Dans la barre située au-dessus de l’aperçu, passez de Preview à Edit.
Cliquez sur le bloc que vous souhaitez modifier.

Le panneau qui s’ouvre peut réécrire le bloc avec l’IA, modifier directement son texte, le raccourcir ou le développer, le transformer en widget de contenu ou le supprimer. Faites glisser un bloc par sa poignée pour le déplacer ; le nouvel ordre est prévisualisé jusqu’à ce que vous cliquiez sur Save ou Revert.

Pour ajouter quelque chose plutôt que le modifier, déplacez le pointeur vers la jonction entre deux blocs. Un bouton plus apparaît et propose un paragraphe, un titre, une liste, un bloc de code, une citation, un encadré, un tableau ou un widget. Add a page, en bas de la barre latérale, crée une page entière à partir d’un titre, d’un dossier et d’une note facultative indiquant ce qu’elle doit couvrir.

Chacune de ces actions est enregistrée dans votre dépôt comme n’importe quelle autre modification, afin que votre source reste l’unique référence. La réécriture d’un bloc avec l’IA appelle un modèle et est facturée sur le solde du projet ; modifier vous-même le texte ne l’est pas.

Annuler une modification que vous avez publiée#

Toute modification publiée par l’assistant peut être annulée depuis le chat, sans ouvrir GitHub.

Immédiatement : appuyez sur la flèche d’annulation de la carte que l’assistant affiche après la publication (« 2 fichiers mis à jour »).
Plus tard : ouvrez l’icône d’horloge dans l’en-tête du chat. Elle répertorie les modifications récentes du projet ainsi que les fichiers touchés par chacune, avec une option d’annulation à côté de chaque entrée.

Cet historique constitue l’historique réel des publications de votre dépôt : il répertorie donc également les modifications effectuées lors d’une session précédente, par un coéquipier ou directement sur GitHub. Elles peuvent toutes être annulées de la même manière.

Une annulation est un nouveau commit qui restaure les fichiers, et non une réécriture de l’historique. Elle apparaît dans la liste comme une entrée distincte marquée Annulation, peut elle-même être annulée et ne supprime jamais les commits des autres. Si une version antérieure d’un fichier ne peut pas être récupérée, elle est signalée comme ignorée plutôt que devinée.

Demandez à l’assistant quoi améliorer#

Demandez à l’assistant quoi corriger — « que dois-je corriger en premier », « rendez ceci trouvable dans les recherches », « ces pages semblent peu fournies » — et la réponse vous revient sous forme de liste à cocher, plutôt que de prose que vous devriez mettre en œuvre manuellement.

Chaque ligne correspond à une modification concrète apportée à l’une de vos pages réelles : ce qu’elle modifie, pourquoi cela aide et quelle page elle concerne. Certaines lignes correspondent à un réglage plutôt qu’à une réécriture et ouvrent la carte qui permet de l’activer. Rien n’est coché au départ. Cochez les lignes souhaitées, appuyez une fois sur Appliquer, et chaque ligne cochée est traitée en une seule passe. Les lignes non cochées ne sont jamais appliquées.

La liste ne repose pas sur des suppositions : l’assistant lit la compétence de documentation couvrant votre demande — recherche et indexation, ton, accessibilité, traduction — vérifie ce qu’il peut mesurer sur votre site, vérifie quelles cartes de réglages existent et formule ses recommandations à partir de ces éléments. Il indique la compétence appliquée.

Ce que fait Appliquer dépend du mode automatique :

Mode automatique	Ce qui se passe lors de l’application
Désactivé (par défaut)	Les modifications vous sont présentées sous forme de différences avant/après que vous approuvez ou rejetez page par page
Activé	Elles sont appliquées et publiées immédiatement, avec un résumé des modifications effectuées
Réglage sélectionné	Sa carte s’ouvre dans le chat afin que vous activiez vous-même l’interrupteur

La génération de la liste et la réécriture des pages font toutes deux appel à un modèle d’IA ; elles sont donc toutes deux déduites du solde du projet.

Docsbook lit les noms de vos fichiers pour ordonner la barre latérale :

Les pages qui permettent au lecteur de commencer — README, introduction, getting-started, quick-start, installation, setup — sont listées en premier.
Les pages destinées à rechercher des informations — reference, api, changelog, faq, troubleshooting — sont listées en dernier.
Tout le reste est classé alphabétiquement entre les deux. Les dossiers sont classés de la même manière selon leurs propres noms.

Les préfixes numériques fonctionnent donc toujours : 1-basics.md est classé avant 2-intermediate.md par ordre alphabétique, et le nombre est ignoré lorsque Docsbook compare le nom aux deux listes ci-dessus.

Si aucune de vos pages ne correspond à l’une ou l’autre liste, la barre latérale suit un ordre alphabétique simple. Renommez un fichier pour le déplacer.

Organisez les fichiers en dossiers#

La barre latérale reflète la structure de vos dossiers, qui constitue donc la navigation. Regroupez les fichiers par thème :

docs/
├── README.md
├── getting-started.md
├── api/
│   ├── overview.md
│   ├── auth.md
│   └── endpoints.md
└── guides/
    ├── deployment.md
    └── troubleshooting.md

Regrouper par thème est préférable à regrouper par difficulté (1-basics.md, 2-advanced.md), car un lecteur arrive depuis un moteur de recherche à la recherche d’un sujet, et non d’un niveau.

Lien entre les pages#

Écrivez des liens markdown relatifs ordinaires. Docsbook les convertit en URL du site lors de la publication.

[Set up a custom domain](/docsbook-io/docs/guides/advanced/custom-domain)
[Create your first site](/docsbook-io/docs/guides/getting-started/creating-docs)
[Frequently asked questions](/docsbook-io/docs/faq)

Créez un lien vers un titre sur la même page avec son ancre :

[Jump to the sidebar order](#understand-the-sidebar-order)

L’ancre correspond au texte du titre en minuscules, les espaces étant remplacés par des traits d’union ; le titre doit donc exister pour que le lien aboutisse.

Ajouter des images#

Placez le fichier image dans votre dépôt, à côté de la page, par exemple dans un dossier images/.
Validez-le.
Référencez-le avec un chemin relatif et décrivez ce qu’il montre :

![GitHub fork dialog with the Create fork button highlighted](https://raw.githubusercontent.com/docsbook-io/docs/main/guides/getting-started/images/fork-dialog.png)

Les formats PNG, JPG, GIF et WebP sont tous pris en charge. Rédigez un véritable texte alternatif pour chaque image porteuse d’informations : c’est ce qu’annonce un lecteur d’écran, ce qu’indexe un moteur de recherche et ce que voit le lecteur lorsque le fichier ne peut pas être chargé.

Contrôler qui peut lire vos documents#

Par défaut, un site Docsbook est public : toute personne disposant du lien peut le consulter, les robots des moteurs de recherche l’indexent et aucun compte GitHub n’est nécessaire. Cela reste vrai même lorsque le dépôt source est privé.

Pour en restreindre l’accès, passez l’espace de travail en mode privé dans Paramètres → Confidentialité & Accès. Un lecteur doit alors le déverrouiller à l’aide d’un mot de passe partagé ou en se connectant via votre propre fournisseur d’identité OIDC — robots inclus. En tant que propriétaire, vous avez toujours accès au site. Configuration complète : Restreindre l’accès à votre site de documentation.

Travailler avec d’autres personnes#

Via GitHub. Ajoutez-les en tant que collaborateurs au dépôt. Ils modifient des fichiers ou ouvrent des demandes de modification, et le site se met à jour lorsqu’une modification atteint votre branche par défaut. C’est la voie à suivre pour toute personne qui travaille déjà dans le dépôt.

Via le chat IA. Cliquez sur Inviter dans la barre d’outils du chat et envoyez une invitation par e-mail ou un lien. Les collaborateurs rejoignent la même session en direct et n’ont donc pas besoin d’un compte GitHub. Leur travail utilise le même solde de projet que le vôtre.

Corriger un site qui n’a pas été mis à jour#

Suivez ces étapes dans l’ordre.

Confirmez que le commit a bien été envoyé sur GitHub. Ouvrez le dépôt et recherchez-le. S’il n’y est pas, il n’a jamais été envoyé.
Actualisez en ignorant le cache de votre navigateur. Ctrl+F5, ou Cmd+Shift+R sur macOS. Une fenêtre privée est le moyen le plus rapide d’écarter un problème de cache.
Attendez quelques minutes. La publication n’est pas instantanée ; Docsbook vérifie périodiquement le dépôt plutôt qu’à chaque frappe.
Vérifiez l’extension du fichier. Seuls les fichiers .md sont publiés.
Vérifiez le nom du fichier. Les lettres latines, les chiffres et les traits d’union sont sûrs ; les autres caractères peuvent empêcher la création d’une URL.

Si certaines pages ont été mises à jour et pas d’autres, il s’agit presque toujours du cache du navigateur plutôt que de la synchronisation — une mise à jour partielle n’est pas un état publié par Docsbook.

Gestion des versions#

Docsbook sert une version de votre documentation : l’état actuel de votre branche. La prise en charge de plusieurs versions publiées côte à côte n’est pas disponible actuellement.

Si vous en avez besoin dès maintenant, conservez les versions dans des branches distinctes (docs/v1, docs/v2) ou dans des dépôts distincts, puis connectez celle que vous souhaitez publier.

Voir qui lit#

Ouvrez le widget flottant → Analytics. Les vues, visiteurs, pages principales, référents et requêtes de recherche sont indiqués par page, afin que vous puissiez voir quelles pages génèrent leur trafic et lesquelles restent non lues.

Deux rapports répondent à la plupart des questions concernant une page : les analyses Web pour le trafic, et les retours sur la page pour savoir si les lecteurs qui sont arrivés ont obtenu ce dont ils avaient besoin.

Supprimer un espace de travail#

Paramètres → Supprimer l’espace de travail supprime le site de documentation et tous ses paramètres. Cette action est irréversible.

Votre dépôt GitHub reste intact. Le markdown reste là où il a toujours été, donc la suppression d’un espace de travail entraîne la perte de la configuration, pas du contenu.

Prochaines étapes#

Configurer un domaine personnalisé — diffusez la documentation depuis une adresse qui vous appartient.
Traduire votre documentation — 15 langues, chacune indexée séparément.
Ce que Docsbook inclut et ce qui est payant — quelles actions utilisent le solde du projet.
Questions fréquemment posées — les questions que les lecteurs posent avant de s’engager.