Source de vérité

La source de vérité est un graphe structuré de l’ensemble de votre documentation — pages, titres, sections et liens croisés — construit localement par des agents d’IA comme Claude Code via markdown-lsp. L’agent exécute l’analyseur sur votre dépôt, conserve le graphe en mémoire et l’interroge — sous forme de commandes ou de requêtes LSP — pendant qu’il travaille sur votre documentation.

Remarque. L’indexation côté serveur de la source de vérité et les outils de graphe MCP hébergés (get_doc_graph, read_doc_sections, reindex_doc_graph et les outils de style LSP doc_*) ont été supprimés dans v0.22.0. Le graphe réside désormais entièrement sur la machine de l’agent : il n’y a pas d’index hébergé, pas de quota de réindexation et rien de tout cela ne puise dans le solde de votre projet.

Comment donner à un agent accès au graphe de référence#

Exécutez markdown-lsp dans le dépôt que vous souhaitez interroger avec l’agent, et le graphe lui est accessible aussi longtemps qu’il y travaille. Rien ne doit être activé dans Docsbook, et vous n’avez pas besoin d’un compte Docsbook.

Le graphe est créé par markdown-lsp — notre serveur de langage Markdown open source, publié sur npm sous le nom markdown-lsp et nécessitant Node 20 ou une version ultérieure. Un agent peut y accéder de deux manières, qui sont véritablement des interfaces différentes plutôt que deux noms pour une seule et même chose :

# 1. As commands the agent runs. Every subcommand prints JSON to stdout.
npx markdown-lsp workspace-outline ./docs
npx markdown-lsp links-to ./docs quick-start.md
 
# 2. As a language server, for an editor or a structural indexer.
npx markdown-lsp lsp --stdio

Pour Claude Code, le paquet fournit une compétence qui configure la première méthode au cours de la conversation :

npx skills add Docsbook-io/markdown-lsp

Il n’y a pas de serveur MCP dans markdown-lsp. Un agent l’utilise en exécutant des commandes ou en communiquant via LSP — c’est pourquoi rien ici ne consomme de jeton MCP ni de solde Docsbook. Consultez le README de markdown-lsp pour obtenir la liste complète des options.

Ce que contient le graphe#

Pour chaque page, le graphe stocke :

• Référence canonique (path#section)
• Titre et frontmatter
• Arborescence des titres avec des ancres stables
• Corps des sections (Markdown)
• Liens sortants et entrants

Chaque commande lit l’arborescence de travail telle qu’elle se présente au moment de son exécution, de sorte que ce que l’agent obtient correspond toujours aux fichiers sur le disque — y compris les modifications qu’il n’a pas validées. Il n’y a aucun cache à invalider sur le chemin structurel.

Comment le graphe est construit#

Le graphe est analysé par markdown-lsp — notre implémentation open source du Language Server Protocol pour Markdown, publiée sur npm sous le nom markdown-lsp. Il est analysé en un AST unified + remark (avec le Markdown au format GitHub), plutôt que par comparaison d’expressions régulières avec le texte, ce qui signifie que :

• Les chemins relatifs comme ../guide.md#section sont résolus vers une page réelle et une ancre réelle
• Les styles de liens inline, de référence et autolink sont tous détectés comme des liens, et pas uniquement la forme inline
• Un lien qui n’aboutit à rien est signalé dès le départ — l’export du graphe contient un unresolvedCount, et chaque arête indique le type de lien dont elle provient

Ce que l’agent peut demander au graphe#

Voici les sous-commandes markdown-lsp. Elles s’exécutent sur le graphe en mémoire construit à partir du disque : elles sont donc instantanées, gratuites et n’effectuent aucun appel vers Docsbook. Chacune prend le répertoire de documentation comme premier argument et affiche du JSON ; --pretty l’indente.

Structure

Recherche

Graphe des liens

Trois autres sous-commandes constituent la couche sémantique et sont les seules à ne pas être strictement locales : index crée un index d’embeddings persistant, semantic-search l’interroge et graph --semantic ajoute des arêtes de similarité. Chacune nécessite une clé de fournisseur d’embeddings dans l’environnement et envoie le texte des pages à ce fournisseur. index est incrémentale — les unités inchangées sont servies depuis le cache local sous .markdown-lsp-cache/, de sorte qu’après la modification d’une seule page, son relancement ne ré-encode qu’une page.

Pourquoi le graphe est-il local plutôt qu’hébergé ?#

Docsbook crée le graphe de la source de vérité sur la machine de l’agent, car les trois éléments dont un agent a besoin — la fraîcheur, la confidentialité et des relectures illimitées — sont précisément les trois qu’un index hébergé ne peut pas fournir.

• Aucun quota ni coût. Réindexez aussi souvent que l’agent en a besoin : tout est stocké sur le disque et aucun appel n’est facturé.
• Toujours à jour. Le graphe reflète les modifications non validées dès que l’agent les enregistre, ce qu’un index hébergé construit à partir de commits envoyés ne peut pas faire.
• Privé. Avec les sous-commandes structurelles, les brouillons non publiés ne quittent jamais la machine : aucune clé n’est configurée et aucune requête n’est effectuée.
• Pas lié à Docsbook. markdown-lsp fonctionne avec n’importe quel dépôt Markdown, y compris la documentation qui n’est pas publiée ici.

Le compromis est réel et mérite d’être explicité : un agent qui n’a pas de copie de travail de votre dépôt ne peut rien tirer de ce graphe. Cet agent doit plutôt utiliser les outils search_docs et get_doc_outline hébergés.

Limites et questions ouvertes#

• « Rien ne quitte la machine » ne s'applique qu'à la partie structurelle. index, semantic-search et graph --semantic envoient le texte des pages à un fournisseur d'embeddings, car c'est précisément ce qu'est un embedding. Si votre documentation est confidentielle, utilisez les sous-commandes structurelles, qui ne nécessitent aucune clé, et évaluez séparément les sous-commandes sémantiques.
• Le serveur LSP n'est pas la CLI. Les sous-commandes construisent leur graphe en mémoire et ne nécessitent aucune base de données ; l'exécution du serveur de langage complet pour un éditeur nécessite Postgres pour son index incrémentiel. Les commandes de cette page correspondent au parcours CLI.
• La fraîcheur est une propriété de l'exécution, pas d'un observateur. Chaque commande lit l'arborescence de travail telle qu'elle se présente au moment de son exécution ; le graphe obtenu par un agent est donc à jour à cet instant. L'index sémantique n'est à jour qu'au dernier index. La recommandation du package lui-même est d'utiliser un hook Git, et non un démon.
• Le graphe connaît la structure des liens, pas leur exactitude. unresolvedCount vous indique qu'un lien ne mène à rien. Rien ici ne vous indique qu'une page est incorrecte, obsolète ou en contradiction avec le produit — c'est le rôle des outils d'analyse et d'historique des modifications du serveur MCP.
• Dépendant de la version. Les noms et options des sous-commandes appartiennent à markdown-lsp, qui évolue selon son propre calendrier. Le README du package fait autorité ; cette page décrit l'interface publiée aujourd'hui.
• Encore en question : les liens [[note]] de style wiki. Une version antérieure de cette page indiquait qu'ils étaient pris en charge. Le package ne documente ni les liens wiki ni un plugin qui les ajoute, et son analyseur est remark avec le Markdown compatible GitHub, qui ne les résout pas de lui-même. Considérez les liens wiki comme non pris en charge jusqu'à indication contraire du package ; les liens Markdown ordinaires dans les trois styles sont couverts ci-dessus.

Connexe#

• Serveur MCP — le serveur hébergé pour l’espace de travail, le contenu, les analyses et les webhooks.
• Compétences Docs — le catalogue de compétences qui s’appuie sur le graphe.
• llms.txt — l’index lisible par machine du site publié, destiné aux agents sans copie locale.
• Sécurité du serveur MCP — ce que la partie hébergée stocke et ce à quoi un jeton peut accéder.
• Webhooks — s’abonner à content.indexed et content.outdated sur la partie hébergée.