Visibility
Show different content to human readers and AI agents on the same page. Agent-only context, instructions, and definitions that stay out of the rendered docs.
Use the <Visibility> component to carve out content for a specific audience. Blocks marked for="humans" appear in the rendered HTML docs; blocks marked for="agents" appear in the raw Markdown export and llms-full.txt that AI agents consume.
The same MDX file serves both audiences. No duplication, no fork.
When to use it
Agents (ChatGPT, Claude, Perplexity, Cursor) often need context that would clutter the rendered page: exhaustive definitions, disambiguation notes, or instructions phrased in a way that reads better to an LLM than a human. <Visibility> lets you write both on one page.
Agents consume your docs through two surfaces: the .md URL (append .md to any page), and llms-full.txt (a single concatenated file). <Visibility for="agents"> content appears on both.
Quick Start
# 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>Humans reading the site see only the dashboard tip. An AI agent reading the .md export sees only the security guidance.
Audiences
for value | Shows in HTML page | Shows in .md export & llms-full.txt |
|---|---|---|
humans | ✓ | — |
agents | — | ✓ |
Examples
Agent-only API context
## 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>Human-only onboarding tip
## 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.Reassuring to a human reading the docs, useless to an agent generating code. Keep it out of the .md export.
Glossary expansion for agents
## 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>Self-closing form
Use a self-closing tag when you want to remove a block from the other audience without replacing it with anything:
<Visibility for="agents" />How audiences are detected
Jamdesk picks an audience from the URL shape and Accept header, never from user-agent sniffing:
| Request | Audience |
|---|---|
Canonical URL (e.g. /guides/auth) | humans |
.md URL (e.g. /guides/auth.md) | agents |
Canonical URL with Accept: text/markdown | agents |
llms-full.txt (built into every site) | agents |
Any agent that sets Accept: text/markdown gets the agent content automatically. No URL surgery required.
Rules & gotchas
Code blocks are safe. The filter detects fenced (triple-backtick or triple-tilde) and inline (single-backtick) code blocks and leaves <Visibility> tags inside them untouched. That's why the examples above render correctly: they contain <Visibility> tags as content, not as components.
JSX expressions are not supported. Wrapping <Visibility> inside a JS expression like {cond && <Visibility for="agents">...</Visibility>} will cause a build error. Use the component at the block level, not inside an expression.
Don't nest <Visibility> blocks. Nesting works for the HTML render surface but is not reliably supported in the .md export or llms-full.txt (the text-level filter used there is not nesting-safe and will produce mangled output). Keep blocks flat.
Site search indexes for="humans" content only. A term that appears only inside a <Visibility for="agents"> block won't surface in the human-facing search autocomplete. The .md export and llms-full.txt still include it for agents.
When NOT to use it
- To hide sensitive information.
<Visibility for="humans">only hides content from the rendered HTML. The raw MDX is still available via.mdURL and inllms-full.txt. If you don't want it visible to anyone, don't put it in your docs repo. - To A/B test content for different users. There are only two audiences: humans and agents. Jamdesk doesn't detect which specific human is viewing. Use feature flags or route redirects for user-segmented content.
- To paper over missing documentation. Agent-only content should be supplementary, not a substitute for clear human-facing docs. If you find yourself writing the real explanation for agents and a stub for humans, flip it.