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, root sitemap/robots files, docs/search-index.json, docs/agent-readability.json, and docs/*.md to a public/ directory your docs website serves. This is what you wire into a Next.js, TanStack Start, Nuxt, Astro, or SvelteKit 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 URL-anchored site files like llms.txt, llms-full.txt, sitemap, and robots. If agents.mcp.enabled is set, also includes the package-local search/readability files used by leadtype mcp --package.

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 emits this for local search and source-grounded answers. Bundle mode includes it only when agents.mcp.enabled is set, so leadtype mcp --package can do targeted retrieval over installed package docs.
`Agent Readability`	`<out>/sitemap.xml + <out>/robots.txt + <out>/docs/agent-readability.json`	-	Site mode emits root crawler discovery files plus structured docs page data. MCP-enabled package bundles include the local manifest without root sitemap or robots files. Host apps can merge this with blog, marketing, changelog, or product pages before serving custom root sitemap and robots files.
`Navigation manifest`	`docs-nav.json (build script)`	-	Resolved nav tree mapping pages to top-level docs areas, sidebar sections, and agent-map locations. Built by the resolveDocsNavigation() helper so your docs shell 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
`site mode`	`noun`	-	The default `leadtype generate` run. Writes website artifacts to `public/`: `llms.txt`, markdown mirrors, `llms-full.txt`, search index, sitemap, robots, and `agent-readability.json`. Use when readers reach you over HTTP.
`bundle mode`	`noun`	-	`leadtype generate --bundle`. Writes `AGENTS.md` plus relative `docs/*.md` into a package directory so coding agents read version-matched docs from `node_modules/<pkg>/AGENTS.md` after install. Skips URL-anchored site files; includes package-local MCP retrieval files when `agents.mcp.enabled` is set.
`source primitive`	`noun`	-	Shorthand for `createDocsSource()` — the framework-neutral function leadtype exposes for page loading, navigation, search input data, include resolution, and TOC data. Use it when your docs app compiles MDX through a bundler (Next, TanStack Start, Nuxt, Astro, SvelteKit).
`Agent Readability`	`noun`	-	The structured discovery and attribution data (`agent-readability.json`, JSON-LD, sitemap, robots, markdown alternate links) that lets agents fetch, identify, and cite docs without scraping rendered HTML. Site mode emits the full HTTP surface; MCP-enabled package bundles include the local manifest used by `leadtype mcp --package`.
`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 legacy taxonomy group a page belongs to. Config nav now drives curated sidebar and agent-map structure; group remains useful for fallback navigation and search facets.
`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, TanStack Start server middleware, Nuxt/Nitro middleware, Astro endpoints, SvelteKit endpoints, or Cloudflare Workers.

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 URL-anchored site files (llms.txt, llms-full.txt, sitemap, robots). If docs.config.ts sets agents.mcp.enabled, also write the package-local search index and Agent Readability manifest used by leadtype mcp --package.

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.