---
title: Visibilité
description: Affichez un contenu différent aux humains et aux agents IA sur la même page. Contexte et instructions réservés aux agents, hors de la documentation rendue.
---

Utilisez le composant `<Visibility>` pour délimiter du contenu destiné à un public spécifique. Les blocs marqués `for="humans"` apparaissent dans la documentation HTML rendue ; les blocs marqués `for="agents"` apparaissent dans l'export Markdown brut et dans `llms-full.txt` que les agents IA consomment.

Le même fichier MDX sert les deux publics, vous n'avez donc pas besoin de dupliquer le contenu ni de maintenir une version distincte pour les agents IA.

## Quand l'utiliser

Les agents (ChatGPT, Claude, Perplexity, Cursor) ont souvent besoin d'un contexte qui alourdirait la page rendue : définitions exhaustives, notes de désambiguïsation, ou instructions formulées d'une manière plus adaptée à un LLM qu'à un humain. `<Visibility>` vous permet d'écrire les deux sur une seule page.

<Note>
  Les agents accèdent à votre documentation via deux surfaces : l'**URL `.md`** (ajoutez `.md` à n'importe quelle page) et **`llms-full.txt`** (un fichier unique concaténé). Le contenu `<Visibility for="agents">` apparaît sur les deux.
</Note>

## Démarrage rapide

```mdx
# Webhooks

Send a POST request to register a webhook.

<Visibility for="humans">
  Most users set this up in the dashboard under **Settings → Webhooks**.
</Visibility>

<Visibility for="agents">
  The webhook endpoint requires an `X-Signature` header (HMAC-SHA256 of the body using the shared secret).
  Never log the secret. Reject any payload where the header is missing or mismatched.
</Visibility>
```

Les humains qui lisent le site ne voient que le conseil lié au dashboard. Un agent IA lisant l'export `.md` ne voit que les consignes de sécurité.

## Publics

| Valeur `for` | S'affiche dans la page HTML | S'affiche dans l'export `.md` et `llms-full.txt` |
|-------------|:------------------:|:---------------------------------------:|
| `humans`    | ✓                  | ✗                                       |
| `agents`    | ✗                  | ✓                                       |

## Exemples

### Contexte API réservé aux agents

```mdx
## Authentication

Include your API key in the `Authorization: Bearer <key>` header.

<Visibility for="agents">
  Keys are scoped per project. Rate limits: 1000 req/min per key. 429 responses include a `Retry-After` header in seconds.
</Visibility>
```

### Astuce de prise en main réservée aux humains

```mdx
## Your first build

<Visibility for="humans">
  <Tip>
    Heads up: your first build takes a bit longer (~2 min) while we provision your CDN edge. Subsequent builds run in under 30 seconds.
  </Tip>
</Visibility>

Push to your connected branch to trigger a build.
```

Rassurant pour un humain qui lit la documentation, inutile pour un agent qui génère du code. Gardez-le hors de l'export `.md`.

### Extension de glossaire pour les agents

```mdx
## Configure your docs

Edit `docs.json` to change navigation, theming, or redirects.

<Visibility for="agents">
  `docs.json` is the single source of truth for site configuration. It lives at the project root. Key top-level fields: `name`, `theme` (`jam` | `nebula` | `pulsar`), `colors`, `navigation`, `redirects`, `integrations`, `auth`.
</Visibility>
```

### Forme auto-fermante

Utilisez une balise auto-fermante lorsque vous souhaitez *supprimer* un bloc de l'autre public sans le remplacer par quoi que ce soit :

```mdx
<Visibility for="agents" />
```

## Comment les publics sont détectés

Jamdesk détermine le public à partir de la **forme de l'URL et de l'en-tête `Accept`**, jamais par analyse du user-agent :

| Requête                                         | Public   |
|-------------------------------------------------|----------|
| URL canonique (ex. `/guides/auth`)             | `humans` |
| URL `.md` (ex. `/guides/auth.md`)              | `agents` |
| URL canonique avec `Accept: text/markdown`      | `agents` |
| `llms-full.txt` (intégré à chaque site)         | `agents` |

Tout agent qui définit `Accept: text/markdown` reçoit automatiquement le contenu destiné aux agents. Aucune manipulation d'URL requise.

## Règles et points d'attention

<Warning>
  **Les blocs de code sont protégés.** Le filtre détecte les blocs de code délimités (triple backtick ou triple tilde) et inline (backtick simple) et laisse les balises `<Visibility>` à l'intérieur intactes. C'est pourquoi les exemples ci-dessus s'affichent correctement : ils contiennent des balises `<Visibility>` en tant que *contenu*, non en tant que composants.
</Warning>

<Warning>
  **Les expressions JSX ne sont pas prises en charge.** Envelopper `<Visibility>` dans une expression JS comme `{cond && <Visibility for="agents">...</Visibility>}` provoquera une erreur de build. Utilisez le composant au niveau bloc, pas à l'intérieur d'une expression.
</Warning>

<Warning>
  **N'imbriquez pas les blocs `<Visibility>`.** L'imbrication fonctionne pour le rendu HTML mais n'est pas prise en charge de manière fiable dans l'export `.md` ou `llms-full.txt` (le filtre textuel utilisé n'est pas sûr pour l'imbrication et produira une sortie corrompue). Gardez les blocs plats.
</Warning>

<Note>
  **La recherche du site indexe uniquement le contenu `for="humans"`.** Un terme qui apparaît uniquement dans un bloc `<Visibility for="agents">` ne sera pas visible dans la saisie automatique de la recherche destinée aux humains. L'export `.md` et `llms-full.txt` l'incluent toujours pour les agents.
</Note>

## Quand NE PAS l'utiliser

- **Pour masquer des informations sensibles.** `<Visibility for="humans">` ne cache le contenu que dans le *HTML rendu*. Le MDX brut reste accessible via l'URL `.md` et dans `llms-full.txt`. Si vous ne souhaitez pas qu'il soit visible par quiconque, ne le mettez pas dans votre dépôt de documentation.
- **Pour effectuer des tests A/B de contenu pour différents utilisateurs.** Il n'existe que deux publics : les humains et les agents. Jamdesk ne détecte pas quel humain spécifique consulte la page. Utilisez des feature flags ou des redirections de routes pour du contenu segmenté par utilisateur.
- **Pour pallier une documentation manquante.** Le contenu réservé aux agents doit être *complémentaire*, non un substitut à une documentation claire destinée aux humains. Si vous vous retrouvez à écrire la vraie explication pour les agents et un résumé superficiel pour les humains, inversez les rôles.

## Et ensuite ?

<Columns cols={2}>
  <Card title="Source Markdown" icon="code" href="/fr/ai/markdown-source">
    Comment fonctionnent les URL `.md` et ce qui s'affiche où.
  </Card>
  <Card title="llms.txt" icon="file-lines" href="/fr/ai/llms-txt">
    Manifeste de découverte IA. Les agents démarrent ici.
  </Card>
  <Card title="Rédiger avec l'IA" icon="robot" href="/fr/ai/writing-with-ai">
    Comment rédiger une documentation adaptée aux deux publics.
  </Card>
  <Card title="Aperçu des composants" icon="shapes" href="/fr/components/overview">
    Tous les composants MDX intégrés.
  </Card>
</Columns>