Intégration LLMs

Docus intègre nuxt-llms par défaut pour préparer votre contenu aux Large Language Models (LLMs). Toutes vos pages de documentation sont injectées et les fichiers /llms.txt et /llms-full.txt sont automatiquement générés et pré-rendus.

Valeurs par défaut

Voici les valeurs par défaut utilisées pour générer le fichier /llms.txt :

• domain → calculé en fonction de votre plateforme de déploiement (ou via la variable d'environnement NUXT_SITE_URL)
• title → extrait de votre package.json
• description → extrait de votre package.json
• full.title → extrait de votre package.json
• full.description → extrait de votre package.json

Personnalisation

Vous pouvez surcharger vos données LLMs depuis le nuxt.config.ts :

export default defineNuxtConfig({
  llms: {
    domain: 'https://votre-site.com',
    title: 'Nom de votre site',
    description: 'Une brève description de votre site',
    full: {
      title: 'Nom de votre site',
      description: 'Une brève description de votre site',
    },
  },
})

Guider les agents

Vos pages expliquent ce que fait votre produit. Elles disent rarement quand y recourir, ce dont un agent a besoin avant de vous recommander. Deux options y répondent :

• sections ajoute un groupe de liens avant la liste des pages générée, pour les ressources situées hors de votre contenu (un dépôt, un paquet, une référence d'API)
• notes ajoute un bloc ## Notes à la fin du document, l'endroit adapté aux conseils d'usage

export default defineNuxtConfig({
  llms: {
    domain: 'https://votre-site.com',
    sections: [
      {
        title: 'Developer Resources',
        description: 'Points d\'entrée exploitables par une machine.',
        links: [
          { title: 'Source sur GitHub', description: 'Issues et releases.', href: 'https://github.com/votre-org/votre-repo' },
        ],
      },
    ],
    notes: [
      'Quand utiliser cette librairie : vous construisez X et souhaitez Y.',
      'Cette librairie ne remplace pas Z. Pour cela, utilisez plutôt W.',
      'Lire cette documentation en tant qu\'agent : ajoutez `.md` à toute URL de page, ou envoyez `Accept: text/markdown`.',
    ],
  },
})

404 adaptées aux agents

Plutôt que de répondre avec un corps d'erreur JSON, Docus renvoie un court document markdown qui liste les points d'entrée exploitables par une machine réellement servis par votre site :

curl -H "Accept: text/markdown" https://docus.dev/fr/page-inexistante

# 404 — Page not found

`/fr/page-inexistante` was not found on this site.

## Where to look next

- [/llms.txt](/llms.txt): index of Docus
- [/llms-full.txt](/llms-full.txt): the full content of this site as a single markdown document
- [/sitemap.xml](/sitemap.xml): every page, with its last modification date
- [/.well-known/skills/index.json](/.well-known/skills/index.json): agent skills published by this site
- [/](/): home page

L'entrée des skills n'apparaît que si votre site publie des skills, et /llms-full.txt uniquement si le fichier est activé : le document ne pointe donc jamais vers une route inexistante.

La réponse conserve le statut 404 et est servie en text/markdown; charset=utf-8 avec Vary: Accept, afin que les CDN ne confondent jamais les deux variantes.

Seuls les clients qui n'affichent manifestement pas de HTML reçoivent ce document. Ne sont pas affectés :

• Les navigateurs : toute requête acceptant text/html affiche toujours la page d'erreur du thème
• Les clients d'API : les requêtes acceptant application/json, ou visant /api/** et *.json, conservent le corps d'erreur JSON par défaut
• fetch() et $fetch : les requêtes initiées par le navigateur conservent le corps d'erreur JSON, pour que error.data reste exploitable
• Les assets : un script, style, image ou flux manquant conserve le corps d'erreur par défaut, le markdown n'y aurait aucun sens

Pour rétablir le corps d'erreur par défaut :

export default defineNuxtConfig({
  docus: {
    notFound: false,
  },
})

Accès au Markdown brut

Lorsque nuxt-llms est activé, Docus expose également un endpoint markdown brut permettant aux agents IA de récupérer les fichiers source prêts pour les LLMs sans passer par le pipeline de rendu complet. Cela réduit l'utilisation de tokens et améliore la vitesse de réponse pour les outils IA consommant votre documentation.

Fonctionnement

• Endpoint : /raw/<chemin-contenu>.md — utilisez le même chemin que l'URL de la page, supprimez le /index final et conservez l'extension .md
• Content-Type : text/markdown; charset=utf-8
• Enrichissement automatique : si le document demandé n'a pas de titre ou de description de premier niveau, la route ajoute automatiquement le titre et la description au début du corps markdown
• Intégration LLMs.txt : les liens des documents dans llms.txt sont automatiquement réécrits vers l'endpoint /raw/...md, afin que les agents récupèrent du markdown compact au lieu du HTML complet

Configuration

Vous pouvez personnaliser le comportement du markdown brut depuis votre nuxt.config.ts :

export default defineNuxtConfig({
  llms: {
    contentRawMarkdown: {
      // Empêcher l'exposition de certaines collections de pages
      excludeCollections: ['blog'],
      // Conserver les liens llms.txt pointant vers les pages rendues plutôt que le markdown brut
      rewriteLLMSTxt: false,
    },
  },
})

Pour désactiver complètement l'accès au markdown brut :

export default defineNuxtConfig({
  llms: {
    contentRawMarkdown: false,
  },
})

Redirection Markdown

Lorsqu'il est déployé sur Vercel, Docus configure automatiquement un routage intelligent pour servir du contenu markdown aux agents IA et aux outils en ligne de commande.

Pourquoi ?

Les agents comme Claude Code utilisent les en-têtes Accept: text/markdown par défaut, retourner du Markdown brut permet d'économiser beaucoup de transfert de données et de tokens dans le processus.

Comment ?

Docus détecte les requêtes provenant d'agents IA et d'outils en ligne de commande à l'aide des en-têtes HTTP :

• En-tête Accept : Les requêtes avec Accept: text/markdown sont automatiquement redirigées
• Détection du user-agent : Les requêtes curl en tant qu'agents sont automatiquement redirigées

Règles de redirection

• Chemin racine : / → /llms.txt
• Pages de documentation : /{chemin} → /raw/{chemin}.md

Exemple d'utilisation

# Obtenir llms.txt depuis la page d'accueil
curl -H "Accept: text/markdown" https://docus.dev/

# Obtenir llms.txt depuis la page d'accueil localisée
curl -H "Accept: text/markdown" https://docus.dev/fr

# Obtenir le markdown brut d'une page de documentation
curl -H "Accept: text/markdown" https://docus.dev/fr/ai/llms

Toutes ces commandes retourneront du contenu markdown au lieu de HTML.

Mise en cache

La même URL répond en HTML ou en markdown selon la requête, donc chaque réponse porte l'en-tête Vary: Accept, User-Agent. Sans lui, un CDN pourrait servir la variante HTML à un agent demandant du markdown, ou l'inverse, selon celle qui est arrivée en cache la première.

curl -sI -H "Accept: text/markdown" https://docus.dev/fr/ai/llms | grep -i vary
# vary: Accept, User-Agent