Using Documints with AI

Every documints site is simultaneously a website and a machine-readable documentation corpus, generated from the same document graph - not a website with an "AI mode" bolted on afterward. This page is the reference for the second half of that: what's available, in what shape, and in what order an agent should reach for it. See Writing Docs for the frontmatter (description, related, prerequisites) that feeds all of it.

Fetching a single page

Every route is available in up to three forms, all at predictable, guessable URLs:

/guides/introduction/deploy       - rendered HTML
/guides/introduction/deploy.md    - raw Markdown source, frontmatter stripped
/guides/introduction/deploy.json  - structured metadata

The .md form is the fastest way to get a page's actual prose with none of the HTML around it. The .json form adds what the Markdown alone doesn't carry - description, related/prerequisites, and headings (the same table of contents the page itself renders, with the same ids as its heading anchors):

{
  "schemaVersion": "1",
  "title": "Deploy",
  "path": "/guides/introduction/deploy",
  "sourceType": "md",
  "markdown": "/guides/introduction/deploy.md",
  "description": "Build and deploy a static documints site to Cloudflare, Netlify, Vercel, GitHub Pages, or AWS.",
  "prerequisites": ["/guides/introduction/getting-started"],
  "headings": [{ "id": "deploy", "text": "Deploy", "level": 1 }]
}

A .doc.tsx page (no raw Markdown source) still has a .json - just with an empty headings array and no markdown field, rather than no file at all.

These URLs are discoverable without already knowing the convention, too - every page's <head> carries the full set:

<link rel="alternate" type="text/markdown" href="/guides/deploy.md" />
<link rel="alternate" type="application/json" href="/guides/deploy.json" />
<link rel="index" href="/docs-manifest.json" />
<link rel="llms.txt" href="/llms.txt" />
<!-- This is a documints site - documentation generated once, published as HTML for
     people and structured data for agents. this page's raw Markdown source is at ...
     (etc. - every href above, restated in one plain-language sentence) -->

The <link> tags are for anything that recognizes a rel value (the same convention a blog uses to advertise its RSS feed from every page, not just the homepage). The comment is the belt-and-suspenders version, for an LLM-based agent reading raw HTML as text rather than parsing it as a DOM - it doesn't need to recognize rel="llms.txt" as meaningful to notice a plain-English sentence saying where everything is. Either way, an agent that lands on one arbitrary page - via a search result, a link from elsewhere, anything that isn't the homepage - never has to already know these conventions exist to find them.

And it's not only for a background agent - "View as Markdown," "Copy as Markdown," "Open in ChatGPT," and "Open in Claude" buttons on every page put the same URLs one click away for a person reading it.

Discovering a whole site

Two endpoints exist for understanding a site's structure without fetching every page:

/.well-known/documints.json  - what this site exposes, and where
/docs-manifest.json          - every document: title, path, hierarchy, description

/.well-known/documints.json (the RFC 8615 convention) is the entry point for an agent that's never seen this particular site before - it only ever advertises formats that actually exist in this build:

{
  "schemaVersion": "1",
  "generator": "documints",
  "version": "0.1.0",
  "manifest": "/docs-manifest.json",
  "llms": "/llms.txt",
  "llmsFull": "/llms-full.txt",
  "formats": { "html": "{path}", "markdown": "{path}.md", "json": "{path}.json" }
}

/docs-manifest.json is the corpus itself, indexed: every document's title, path, sourceType, description, and where it sits in the hierarchy (section/parent/ children, already resolved past any purely-organizational nav groupings - a manifest parent/child reference always points at a real, fetchable document).

Ingesting everything at once

/llms.txt       - a Markdown index of every page, with descriptions
/llms-full.txt  - every page's raw Markdown, concatenated into one file

The llms.txt convention. Use llms-full.txt when ingesting the whole site in one request is appropriate for the task at hand - a small-to-medium docs site fits comfortably in a single fetch this way. For anything larger, or when only part of the site is relevant, prefer the manifest plus targeted .md fetches instead.

Search

The one representation in this whole system that isn't a plain static file an agent can fetch directly: every build indexes the prerendered HTML with Pagefind - a fully static search library, no external service, account, or API key - and writes the result to pagefind/ in the build output. It's built primarily for a person (a "Search" button in the header, Cmd+K/Ctrl+K also opens it, showing Pagefind's own default UI in a modal), not for an agent to query over HTTP - for machine consumption, docs-manifest.json and llms.txt/llms-full.txt are the better fit.

Because Pagefind indexes the built HTML, there's nothing to search against in documints dev - the button still opens the same modal there (useful for checking styling), it just won't return real results until the site is built.

Recommended workflow

Fetch /.well-known/documints.json to confirm this is a documints site and see what it exposes.
Fetch /docs-manifest.json to get every document's title, description, and place in the hierarchy.
Use titles/descriptions (and related/prerequisites, where set) to identify which documents are actually relevant - without fetching any of them yet.
Fetch the .md of each relevant document for its actual content.
Fetch a document's .json instead of (or alongside) its .md when you specifically need headings or its structured metadata, not just prose.
Reach for llms-full.txt only when the task genuinely calls for the whole corpus at once
- a targeted .md fetch is cheaper whenever you already know which page you need.

Using this with a specific tool

The mechanism above is plain HTTP and static JSON/Markdown - nothing here is specific to any one agent or client. A few notes on wiring it into what you're already using:

Claude Code, Cursor, or anything reading a repo-level instructions file (CLAUDE.md, .cursor/rules, AGENTS.md): point it at this site's /.well-known/documints.json in a couple of sentences, the same way you'd document any other internal API. Documints doesn't generate that file for you - it's your project's own instructions file, and this is one more thing worth telling it about.
Codex, or any agent you're driving via a prompt rather than a config file: give it the /.well-known/documints.json URL directly and let the recommended workflow above take it from there - the discovery document is designed to be the only URL an agent needs to be told about up front.
A generic script, RAG pipeline, or search indexer: docs-manifest.json plus per-page .md/.json fetches is a complete, stable ingestion path - no HTML parsing, no scraping, no separate export step to maintain.

None of this requires an MCP server, a REST API, or a hosted service - it's the same static files a browser or crawler already gets, just structured for a machine to use directly.

on this page

Fetching a single page
Discovering a whole site
Ingesting everything at once
Search
Recommended workflow
Using this with a specific tool

View as MarkdownEdit this page