Skip to content

AI-ready published sites

Every Topicary published site automatically exposes machine-readable endpoints that AI tools can consume. No configuration required. These endpoints are live as soon as you publish.

"AI-ready" means every published site exposes structured Markdown endpoints alongside the HTML site. AI tools can programmatically discover your documentation structure through llms.txt, retrieve individual pages as clean Markdown, and query your docs directly through the Ask endpoint, all without scraping or parsing HTML.

Endpoints

Endpoint

URL Pattern

Format

Description

llms.txt

https://your-site/llms.txt

Text

Page index following the llms.txt convention with titles, descriptions, and Markdown links

llms-full.txt

https://your-site/llms-full.txt

Markdown

Complete documentation as a single file, pages separated by horizontal rules

sitemap.md

https://your-site/sitemap.md

Markdown

Hierarchical sitemap with .md URLs and total page count

Per-page Markdown

https://your-site/{slug}.md

Markdown

Individual page as clean Markdown with components expanded, conditions resolved, variables substituted

Ask endpoint

https://your-site/{slug}.md?ask={question}

Markdown

AI-generated answer using your documentation as context

Smart 404

Any non-existent .md URL

Markdown

Up to 5 suggested pages, discovery links, and Ask endpoint instructions

llms.txt

URL: https://your-site/llms.txt

A page index following the llms.txt convention. Returns your site name, description, and a hierarchical list of all pages with brief descriptions (first 150 characters) and links to their Markdown versions.

AI tools that support llms.txt use this as an entry point to discover and understand your documentation structure.

llms-full.txt

URL: https://your-site/llms-full.txt

The complete documentation as a single Markdown file. Each page is separated by a horizontal rule with a source URL. Pages appear in navigation order.

Use this when an AI tool needs full context, for example loading your entire docs into a conversation or building a RAG (retrieval-augmented generation) index.

sitemap.md

URL: https://your-site/sitemap.md

A Markdown-formatted sitemap listing every page with its .md URL and a total page count. Pages appear in navigation order with indentation reflecting the map hierarchy.

Per-page Markdown

URL: https://your-site/{slug}.md

Any published page is available as clean Markdown by appending .md to its URL. The Markdown includes the page title as an H1 heading. The full rendered content follows, with components expanded, conditions resolved, and variables substituted.

Ask endpoint

URL: https://your-site/{slug}.md?ask={question}

Appending ?ask= to any .md URL sends a question to an AI model with your documentation as context. The response is a Markdown-formatted answer.

Constraint

Value

Question limit

2,000 characters

Rate limit (per IP)

10 requests each minute for each IP address

Rate limit (per site)

30 requests each minute across the whole site

Plan requirement

Available on every plan, including Free

The endpoint searches for the most relevant pages to use as context. If embeddings are not available, it falls back to using the full published content.

The Ask endpoint works on any .md URL, so you can scope questions to a specific page's context by choosing the most relevant slug. For broad questions, use the root slug.

Smart 404 responses

If an AI tool requests a .md URL that does not exist, the response includes:

  • Up to 5 suggested pages based on fuzzy title and slug matching

  • Links to sitemap.md and llms-full.txt for discovery

  • Instructions for using the ?ask= endpoint

This helps AI agents recover from broken or guessed URLs without returning an empty error.

How AI tools use these endpoints

AI Tool Category

Recommended Endpoint

Use Case

Coding assistants (Claude Code, Cursor)

llms.txt + per-page .md

Discover structure, then retrieve targeted pages for context

MCP (Model Context Protocol) servers

llms-full.txt or per-page .md

Complete snapshot or granular page access

Conversational AI (ChatGPT, Claude)

llms-full.txt or ?ask=

Full documentation context or direct Q&A

RAG pipelines

llms-full.txt or sitemap.md

Index all pages for retrieval-augmented generation

Example: fetching a page as Markdown 

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

Response:

# Getting started

Welcome to the product documentation. This guide walks you through...

Example: using the Ask endpoint 

curl "https://docs.example.com/getting-started.md?ask=How%20do%20I%20set%20up%20SSO%3F"

Response:

To set up SSO, navigate to Settings > Authentication and follow these steps...

Caching

The Markdown endpoints (llms.txt, llms-full.txt, sitemap.md, and per-page .md) are served with Cache-Control: public, max-age=300, s-maxage=300, stale-while-revalidate=86400, fresh for 5 minutes, then served stale while revalidating in the background for up to 24 hours. Republishing invalidates the cache, so updated content propagates on the next request. The Ask endpoint (?ask=) is not cached, since each question generates a fresh answer.

See also

Was this page helpful?