> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://vocs.dev/api/mcp` to find what you need.
>
> **Have feedback?** Use `submit_feedback` on the same MCP server.

# Agent Support \[Serve documentation in machine-readable form for AI agents]

## Markdown Rendering for AI Agents

Vocs automatically detects AI user agents and serves them raw Markdown instead of rendered HTML. This provides better token efficiency and easier parsing for LLMs.

### Supported AI Agents

The following user agents are automatically detected:

* **OpenAI**: `GPTBot`, `OAI-SearchBot`, `ChatGPT-User`
* **Anthropic**: `anthropic-ai`, `ClaudeBot`, `claude-web`
* **Google**: `Google-Extended`, `GoogleAgent-Mariner`
* **Perplexity**: `PerplexityBot`, `Perplexity-User`
* **Mistral**: `MistralAI-User`
* **Cohere**: `cohere-ai`
* **Others**: `FacebookBot`, `meta-externalagent`, `Bytespider`, `AI2Bot`, and more

Search engine crawlers such as `Googlebot`, `Bingbot`, `Amazonbot`, and `Applebot` continue to receive rendered HTML so standard indexing behavior is preserved.

### Manual Markdown Access

Most pages can be accessed as Markdown by appending `.md` to the URL:

```
https://docs.example.com/getting-started.md
```

For the home page, use:

```
https://docs.example.com/index.md
```

This is useful for copying documentation into AI conversations or for custom integrations.

When the [MCP server](/features/mcp-server) is enabled, each generated Markdown page starts
with its endpoint and suggests using `search_docs`. If feedback is also configured,
the prelude suggests the `submit_feedback` tool. These instructions are not repeated in
`llms.txt` or `llms-full.txt`.

## llms.txt Files

Vocs automatically generates [`llms.txt`](https://llmstxt.org/) files for LLM consumption:

* `/llms.txt` — A concise index of all pages with titles and descriptions.
* `/llms-full.txt` — Complete documentation content concatenated into a single file.

These files are generated at build time and served at the root of your site. No configuration is required.

### Example Output

```txt
# Vocs

Vocs is a library for creating documentation websites.

- [What is Vocs?](/introduction/what-is-vocs): Learn about Vocs and its features
- [Getting Started](/introduction/getting-started): Quick start guide
- [Agent Support](/features/agent-support): Machine-readable docs for AI agents
```

## Custom Component Markdown

Custom MDX components can provide Markdown for AI-facing output without changing their interactive rendering. Define `toMarkdown` on the component, then use the component as a standalone MDX tag.

```tsx [src/components/ClientPrompt.tsx]
const prompt = 'Add mppx to my app as a client.'

export const ClientPrompt = Object.assign(
  function ClientPrompt() {
    return <pre>{prompt}</pre>
  },
  {
    toMarkdown: () => ({
      type: 'code',
      lang: 'text',
      value: prompt,
    }),
  },
)
```

```mdx [src/pages/quickstart.mdx]
import { ClientPrompt } from '../components/ClientPrompt'

<ClientPrompt />
```

Vocs invokes the hook only while generating `.md`, `llms.txt`, and `llms-full.txt`. The hook must return a Markdown AST node or an array of nodes; components without a hook remain unchanged.

### Audit Markdown Components

Dry render every page locally to find components that remain as MDX in AI-facing Markdown:

```sh
vocs markdown-audit
```

The report groups results by component, then lists each affected page and a suggested fix. It exits with status `1` when a component remains unrendered, so it can be used in CI. Add `--json` for machine-readable output.

#### Example Output

```txt
[vocs] Markdown audit found 1 component left after dry rendering 1 page (2 occurrences).

Components:
  InteractiveWidget (2 occurrences)
    Fix: add `InteractiveWidget.toMarkdown` to return a Markdown AST node.
    /guides/setup (2 occurrences)
```

#### JSON Output

```json
{
  "components": [
    {
      "name": "InteractiveWidget",
      "unsupportedUsages": 0,
      "count": 2,
      "pages": [{ "path": "/guides/setup", "count": 2 }]
    }
  ],
  "errors": []
}
```

## Best Practices

### Optimize for LLMs

1. **Write descriptive titles.** Use clear, descriptive page titles that help LLMs understand content.
2. **Add descriptions.** Include `description` in frontmatter for better `llms.txt` output.
3. **Structure content.** Use headings, lists, and code blocks for easy parsing.
4. **Keep pages focused.** Single-topic pages are easier for LLMs to retrieve and reference.

## See More

<Cards>
  <Card title="Ask AI" description="User-facing AI menu on every page." icon="sparkles" to="/features/ask-ai" />

  <Card title="MCP Server" description="Expose docs to AI clients via Model Context Protocol." icon="plug" to="/features/mcp-server" />

  <Card title="Writing Docs with AI" description="Workflow for authoring docs with AI agents." icon="pen-tool" to="/introduction/writing-docs-with-ai" />
</Cards>