Publish documentation for humans and agents

Agent-readable documentation should not be a second, shortened copy of the site. Separate content pipelines drift: a corrected example reaches the rendered page while an old answer remains in a generated prompt file or private index.

Ginko Docs starts from one document model and projects it into several representations. Readers get the full Nuxt page. Search gets normalized records. Static deployments receive raw Markdown and catalogs. Server deployments can add request-time negotiation and MCP tools.

Keep explicit Markdown URLs

Every public content route has an explicit raw counterpart under /raw with a .md suffix. A link to that file works on a static host, in curl, and in tools that cannot send custom Accept headers.

curl https://docs.example.com/raw/docs/getting-started.md

This is the most portable agent interface because it behaves like an ordinary generated file.

Use catalogs for discovery

/llms.txt provides a compact list of available pages. /llms-full.txt combines the public corpus for clients that prefer one larger context. Localized sites also generate locale-specific catalogs.

Catalogs solve discovery, not ranking or authorization. Keep private documentation out of the public collection instead of expecting an LLM catalog to enforce access control.

Add runtime interfaces deliberately

A Nitro server can return Markdown from a normal page URL when the request sends Accept: text/markdown. It can also expose /mcp, where list-pages returns the default catalog and get-page reads the raw Markdown for an explicit public path.

These features require server code. A static host still has the explicit raw routes and catalogs but cannot negotiate responses or execute MCP tools.

Preserve meaning in custom components

Standard Markdown converts naturally. A custom component may need more care. Ginko Docs registers safe default serializers for its built-in tags, producing an XML-style component representation with static props and rendered children.

When a component represents something semantic that should read differently—an API explorer, benchmark, or product state—register a serializer through @lupinum/ginko-content/agent-registry. Keep the serializer beside the component contract so visual and machine-readable changes are reviewed together.

The agent-readable output guide includes the deployment matrix and configuration boundaries. Check the rendered page, raw route, and catalog entry after changing a component that carries meaning; all three should describe the same fact.