How it works

Leadtype takes one input — a folder of MDX — and produces every shape your docs need to take. This page names every piece so the rest of the docs make sense.

The pipeline

Rendering diagram...

The remark stack is what turns interactive MDX components into agent-readable markdown. JSX gets flattened — a <Callout> becomes a blockquote, a <Tabs> becomes a sequence of bold headings, a <TypeTable> becomes a markdown table. The flattened markdown is what every other artifact consumes.

For the exact stack, see Remark plugins. For the component contract, see Components.

Two output modes

leadtype generate has two modes that read the same source and emit different shapes:

Name	Type	Default	Description
`Site mode (default)`	`leadtype generate --out public`	-	Writes llms.txt, llms-full.txt, docs/search-index.json, docs/sitemap.xml, docs/sitemap.md, docs/robots.txt, docs/agent-readability.json, and docs/*.md to a public/ directory your docs website serves. This is what you wire into a Vite, Next.js, Astro, or TanStack Start build.
`Bundle mode`	`leadtype generate --bundle --out packages/foo`	-	Writes AGENTS.md at the package root and docs/*.md beneath it, both with relative paths. Skips llms.txt, llms-full.txt, search, sitemap, robots, and Agent Readability files — those are website-only. Designed for npm tarballs that ship docs alongside the published code.

The artifacts

Name	Type	Default	Description
`Markdown (.md)`	`docs/<path>.md`	-	Flattened markdown for each MDX page. Both modes ship these. Served to HTTP agents via content negotiation in site mode; read directly from node_modules in bundle mode.
`AGENTS.md`	`<package-root>/AGENTS.md`	-	Bundle mode only. Offline-readable package index. Every link is a relative ./docs/<path>.md path so the file works inside an installed npm package.
`llms.txt + llms-full.txt`	`<out>/llms.txt + <out>/llms-full.txt`	-	Site mode only. Agents fetch /llms.txt over HTTP and follow page-level markdown links first. The root /llms-full.txt file is a broad all-docs fallback when page links are not enough. Useless inside an npm tarball, so bundle mode skips this.
`Search index`	`<out>/docs/search-index.json + search-content.json`	-	Site mode only. BM25-ranked inverted index over headings, titles, body, and code. Content is stored separately so the index stays small. Bundle mode skips it — agents reading from disk grep the .md files directly.
`Agent Readability`	`<out>/docs/sitemap.xml + <out>/docs/sitemap.md + <out>/docs/robots.txt + <out>/docs/agent-readability.json`	-	Site mode only. Docs-scoped discovery files and structured page data. Host apps merge this with blog, marketing, changelog, or product pages before serving root sitemap and robots files.
`Navigation manifest`	`docs-nav.json (build script)`	-	Resolved group tree mapping pages to nav locations. Built by the resolveDocsNavigation() helper so your sidebar component and your llms.txt sections agree on structure.

The three audiences

Rendering diagram...

Humans see the HTML your docs site renders from MDX.
HTTP agents fetch /llms.txt over the network or use Accept: text/markdown content negotiation to get the converted .md from your docs site URL.
Coding agents working in a project that depends on your package can read node_modules/<your-package>/AGENTS.md for version-matched offline docs. The reliable consumer pattern is to point the consuming project's root AGENTS.md or README at that file. From there they follow relative ./docs/<topic>.md links.

The two flows complement each other. A package that wants to be agent-friendly publishes both: --bundle output inside the tarball and a hosted website with llms.txt. Different agents use different flows; you don't pick one.

Vocabulary

A few terms you will see throughout the docs.

Name	Type	Default	Description
`flatten`	`verb`	-	Convert an interactive MDX component into a portable markdown equivalent. A <Callout> flattens to a blockquote; a <Tabs> flattens to a stack of bold headings.
`group`	`frontmatter field`	-	A slug declaring which group a page belongs to. The same string drives the sidebar position, the llms.txt section, search metadata, and AGENTS.md grouping.
`leaf`	`noun`	-	A group that has no children. Leaves can directly contain pages in the navigation tree; non-leaf groups are summary headings only.
`chunk`	`noun`	-	A heading-aware slice of a page that the search index scores independently. Titles weigh 4×, headings 2×, body 1×, code 0.35×.
`content negotiation`	`noun`	-	Middleware or route logic that returns generated markdown when a request advertises Accept: text/markdown, uses an AI user agent, or asks for /docs/foo.md. Same content, two formats. Implement it wherever your framework intercepts requests — Next.js route handlers, Astro endpoints, Cloudflare Workers, Vite plugins, or server middleware.

What runs when

The leadtype generate command runs in a fixed order — each stage depends on the previous one's output:

Parse frontmatter for every .mdx under docs/.
Convert each file through the default remark stack and write .md to the output directory (e.g. public/docs/ in site mode, <package>/docs/ with --bundle).
Resolve groups from frontmatter, validate every page's group: matches a known slug.
In site mode (default): generate llms.txt, root llms-full.txt, the BM25 search index, and Agent Readability discovery files from the converted markdown.
With --bundle: write AGENTS.md at the output root with relative ./docs/<topic>.md links. Skip llms.txt, llms-full.txt, search, sitemap, robots, and Agent Readability files — those are website-only.

If step 3 finds an unknown group, the run fails. That is by design — broken navigation is a content bug, not a render-time problem.

Where to next

Quickstart

Run the pipeline yourself in five minutes.

Frontmatter contract

The required fields, the group resolution rules, and the lint checks.

CLI reference

Every flag for leadtype generate and leadtype lint.