Notifications
Clear all
Topic starter
06/06/2026 2:18 am
TL;DR: AI agents are increasingly fetching developer documentation directly, but HTML, SPA chrome, and component-heavy pages can waste context or hide the content entirely; WorkOS describes serving clean markdown via content negotiation and AST rendering to reduce parsing failures. The real issue is governance of machine consumers, where unreadable docs become an identity and access problem for automated tooling, not just a formatting choice.
NHIMG editorial — based on content published by WorkOS: Your docs have a new audience AI agents are reading your documentation
Questions worth separating out
Q: How should security teams handle documentation that is consumed by AI agents?
A: Security teams should treat agent-facing documentation as a governed machine interface, not a publishing detail.
Q: Why do AI agents make content delivery a governance issue?
A: AI agents do not tolerate ambiguity the way humans do.
Q: What breaks when docs are built for browsers instead of agents?
A: Agents can lose time, context, or even the core meaning of the page when important content is trapped inside scripts, interactive components, or multi-step navigation.
Practitioner guidance
- Expose a machine-readable documentation path Serve markdown or another plain-text representation for clients that are expected to be consumed by agents.
- Strip presentation-only components before serialization Parse MDX or similar source into an AST, then render tables, code samples, and other structured content into markdown equivalents that preserve meaning for non-human consumers.
- Audit fallback and redirect ordering Ensure redirects, rewrites, and route resolution complete before any agent-facing content fallback runs so a deep link cannot collapse into a broader page with a misleading 200 response.
What's in the full article
WorkOS's full post covers the operational detail this post intentionally leaves for the source:
- The exact Next.js middleware pattern used to detect markdown-capable requests and route them to an internal API path.
- The AST parsing and component-rendering approach used to turn MDX into agent-readable markdown while preserving structured content.
- The fallback User-Agent heuristic and the trade-offs of serving markdown to clients that do not advertise themselves cleanly.
- The routing bug that caused deep links to collapse into broader pages, plus the middleware ordering fix that resolved it.
👉 Read WorkOS's analysis of markdown delivery for AI agent documentation →
AI agent docs and markdown delivery: are your docs ready?
Explore further
06/06/2026 3:54 am
Agent-readable documentation is now an access control problem, not just a UX problem. When a non-human consumer is allowed to fetch a resource, the organisation is implicitly deciding that the response format, content order, and fallback behaviour are trustworthy enough for machine consumption. That is an NHI governance decision in practice, even if no secret or token is involved. The practitioner implication is that documentation delivery needs the same scrutiny as other machine-facing interfaces.
A few things that frame the scale:
- Only 44% of developers are reported to follow security best practices for secrets management, exposing a significant developer behaviour gap, according to The State of Secrets in AppSec.
- In the same research, organisations maintain an average of 6 distinct secrets manager instances, a fragmentation pattern that makes any machine-facing governance model harder to enforce.
A question worth separating out:
Q: How do you know if agent-facing documentation is actually working?
A: Check whether the machine-readable version returns the same meaning as the human page, whether deep links resolve to the right section, and whether structured elements survive serialization. If the agent gets a different page, a broader fallback, or incomplete component output, the documentation pipeline is not functioning as intended.
👉 Read our full editorial: AI agent docs need markdown, not HTML, to stay usable
