api-extractor-llms

Turn a Microsoft API Extractor .api.json model into plain markdown that reads cleanly for both people and language models. You get one markdown document per top-level export — an H1, the summary, a fenced ts signature, parameters, returns, container members and examples — with no site chrome, no HTML and no framework coupling.

Why api-extractor-llms

API Extractor already understands your .d.ts surface. What it will not do is hand you docs you can drop into a prompt, a wiki or a static site. That is the gap this package closes. The body of every rendered doc stays the same no matter where it ends up. Two things change between consumers: the frontmatter block at the top and the URL scheme for cross-links. You inject both, so one renderer feeds an RSPress site, an MCP server or a folder of bare .md files.

Install

npm install api-extractor-llms
# or
pnpm add api-extractor-llms

The package is also published to GitHub Packages as @spencerbeggs/api-extractor-llms if you prefer the scoped name; point your registry at https://npm.pkg.github.com for that scope and install it the same way.

This is an ESM-only package. Import it from a module context ("type": "module" or .mjs).

Quick start

Load a model, render it, then write each doc wherever you want. The library does no I/O of its own. File writing is yours.

import { mkdir, writeFile } from "node:fs/promises";
import { loadApiModel, renderPackage } from "api-extractor-llms";

const pkg = await loadApiModel("./temp/my-pkg.api.json");

const docs = renderPackage(pkg, {
  packageName: "my-pkg",
  routeFor: (ref) => `/api/${ref.slug}`,
});

await mkdir("./out", { recursive: true });
for (const doc of docs) {
  await writeFile(`./out/${doc.slug}.md`, doc.markdown);
}

console.log(docs.map((d) => `${d.kind}: ${d.name}`));
// e.g. [ 'function: loadApiModel', 'class: CrossLinker', 'type: RenderedDoc' ]
// (the actual list depends on your model's exports)

Each entry in the returned array is a RenderedDoc with name, kind, slug, summary, packageName and the assembled markdown.

Inject frontmatter

Pass a frontmatter function to prepend a block — YAML, TOML or whatever your target expects. Omit it for bare bodies.

const docs = renderPackage(pkg, {
  packageName: "my-pkg",
  frontmatter: (meta) => `---\ntitle: ${meta.name}\nkind: ${meta.kind}\n---\n\n`,
});

console.log(docs[0].markdown.startsWith("---"));
// true

routeFor and frontmatter are independent. Supply either, both or neither.

Features

• loadApiModel(path) reads a .api.json file from disk and returns its ApiPackage.
• renderPackage(pkg, opts) walks the first entry point and returns one RenderedDoc per top-level member.
• renderItem(item, opts) renders a single API item to a markdown body, with an optional CrossLinker.
• CrossLinker wraps known item names in prose with links, skipping code spans and existing links, using your injected route scheme.
• TypeSignatureFormatter formats an API Extractor Excerpt into a clean type signature, wrapping long unions across lines.
• TSDoc helpers — getSummary, getParams, getReturns, getExamples, getDeprecation, getReleaseTag, hasModifierTag and extractPlainText — pull plain data off an ApiItem with no rendering.

Generating a model

This package consumes the JSON that Microsoft API Extractor produces. Run API Extractor against your project first with docModel.enabled set in your api-extractor.json, then feed the resulting .api.json to loadApiModel.

License

MIT