@lpsmods/docs-generator

Generate Markdown API documentation from JavaScript, TypeScript, TSX, and Python source files. The generator uses Tree-sitter for parsing and Mustache for templates.

Install

Requires Node.js 20 or newer.

npm install @lpsmods/docs-generator

Usage

Generate documentation for a directory:

import { generateDirectory } from "@lpsmods/docs-generator";

await generateDirectory({
  input: "src",
  output: "docs/api",
});

Generate Markdown from a source string:

import { generate } from "@lpsmods/docs-generator";

const markdown = generate({
  source: `/** Add two numbers. */\nexport function add(a, b) { return a + b; }`,
  language: "javascript",
  title: "Math API",
});

Generate Markdown documentation directly from an OpenAPI 3.x JSON URL:

import { generateOpenApi } from "@lpsmods/docs-generator";

await generateOpenApi({
  input: "https://api.lpsmods.dev/openapi.json",
  output: "docs/openapi",
  vitepress: { sidebar: "docs/sidebar.json" },
});

This writes an index.md and one Markdown file per OpenAPI tag. Operations with no tags are written to untagged.md.

Agent-readable llms.txt, llms-full.txt, and manifest.json files are also generated by default. Set agentDocs: false to omit them.

Use template to customize tag pages and indexTemplate to customize the index. Both accept Mustache strings; partials and view are also supported. The packaged defaults are templates/openapi/tag.mustache and templates/openapi/index.mustache; these files are read at generation time.

OpenAPI can also be added to normal directory generation as a provider:

import { generateDirectory, openApiProvider } from "@lpsmods/docs-generator";

await generateDirectory({
  input: "src",
  output: "docs/api",
  providers: [
    openApiProvider({
      input: "https://api.lpsmods.dev/openapi.json",
      output: "http-api",
    }),
  ],
});

Other available functions include generateFile() for a single file and generateRegistryPackage() for published npm or PyPI packages.

CLI

# File or directory
docs-generator src/example.ts -o docs/example.md
docs-generator src -o docs/api

# Published package
docs-generator npm:yocto-queue@1.2.1 -o docs/yocto-queue
docs-generator pypi:six==1.17.0 -o docs/six

# OpenAPI JSON URL
docs-generator https://api.lpsmods.dev/openapi.json -o docs/openapi

Useful options:

-o, --output <path>       Output path
-l, --language <name>     Restrict the source language
-t, --template <path>     Use a Mustache template
--title <title>           Set the documentation title
--vitepress-sidebar       Generate sidebar.json
--no-agent-docs           Skip agent-readable output
--no-cache                Disable the registry cache
--refresh-cache           Refresh the registry cache
-V, --version             Print the version

Output

All file-writing generators create regular Markdown pages plus agent-readable files by default:

• llms.txt — package summary and links
• llms-full.txt — combined symbol documentation
• manifest.json — machine-readable symbol graph
• symbols/ — one Markdown file per top-level symbol

Set agentDocs: false or pass --no-agent-docs to omit these files. The in-memory generate() function is the sole exception because it does not write files. Set vitepressSidebar: true or pass --vitepress-sidebar to create a VitePress sidebar.

The default agent output is implemented by the exported agentDocumentationProvider(). Directory generation registers this provider automatically unless agentDocs is false, and task runners may invoke the provider directly when composing their own documentation pipeline.

Templates

Pass a Mustache string with template, or use one of the templates included in the package:

• default.mustache — complete documentation
• compact.mustache — shorter symbol layout
• class.mustache, functions.mustache, and declaration.mustache — page-specific layouts

Resolve a packaged template before passing it to the CLI:

const template =
  require.resolve("@lpsmods/docs-generator/templates/compact.mustache");

Templates receive the documentation metadata and symbol collections, including classes, functions, interfaces, types, and enums. Custom data can be supplied with view, and Mustache partials with partials.

Extensions

Use registerLanguage() to add another Tree-sitter grammar. Use the providers option to add framework-specific analysis and generated pages.

import { generateDirectory } from "@lpsmods/docs-generator";
import { myProvider } from "my-docs-provider";

await generateDirectory({
  input: "src",
  output: "docs",
  providers: [myProvider],
});

Providers are loaded explicitly and may contribute symbols, analysis data, files, and sidebar entries.

License

MIT