typedoc-plugin-llms-txt 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-01-16)
+
+
+### Features
+
+* add implementation ([ea61a1f](https://github.com/boneskull/typedoc-plugin-llms-txt/commit/ea61a1f370f7eb00070cf504e27da3a02bcfce1e))

package/LICENSE

@@ -0,0 +1,55 @@
+# Blue Oak Model License
+
+Version 1.0.0
+
+## Purpose
+
+This license gives everyone as much permission to work with
+this software as possible, while protecting contributors
+from liability.
+
+## Acceptance
+
+In order to receive this license, you must agree to its
+rules. The rules of this license are both obligations
+under that agreement and conditions to your license.
+You must not do anything with this software that triggers
+a rule that you cannot or will not follow.
+
+## Copyright
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe that contributor's
+copyright in it.
+
+## Notices
+
+You must ensure that everyone who gets a copy of
+any part of this software from you, with or without
+changes, also gets the text of this license or a link to
+<https://blueoakcouncil.org/license/1.0.0>.
+
+## Excuse
+
+If anyone notifies you in writing that you have not
+complied with [Notices](#notices), you can keep your
+license by taking all practical steps to comply within 30
+days after the notice. If you do not do so, your license
+ends immediately.
+
+## Patent
+
+Each contributor licenses you to do everything with this
+software that would otherwise infringe any patent claims
+they can license or become able to license.
+
+## Reliability
+
+No contributor can revoke this license.
+
+## No Liability
+
+**_As far as the law allows, this software comes as is,
+without any warranty or condition, and no contributor
+will be liable to anyone for any damages related to this
+software or this license, under any kind of legal claim._**

package/README.md

@@ -0,0 +1,130 @@
+# typedoc-plugin-llms-txt
+
+A TypeDoc plugin that generates `llms.txt` files for LLM consumption.
+
+## What is llms.txt?
+
+[llms.txt](https://llmstxt.org/) is a convention for providing LLM-friendly documentation summaries. This plugin automatically generates an `llms.txt` file from your TypeDoc documentation.
+
+## Installation
+
+```bash
+npm install typedoc-plugin-llms-txt typedoc -D
+```
+
+## Usage
+
+Add the plugin to your TypeDoc configuration:
+
+```js
+// typedoc.config.js
+export default {
+  plugin: ['typedoc-plugin-llms-txt'],
+  // ... other options
+};
+```
+
+That's it! The plugin will generate an `llms.txt` file in your output directory with reasonable defaults.
+
+## Zero-Config Defaults
+
+The plugin works out of the box with sensible defaults:
+
+- **Project name**: From TypeDoc's `name` option
+- **Description**: From your `package.json` description
+- **Sections**: Auto-discovered from `projectDocuments` frontmatter categories
+- **API links**: Auto-generated from TypeDoc entry points
+
+## Configuration
+
+Customize the output with these TypeDoc options:
+
+### `llmsTxt`
+
+Enable or disable llms.txt generation. Default: `true`
+
+### `llmsTxtFilename`
+
+Output filename. Default: `"llms.txt"`
+
+### `llmsTxtHeader`
+
+Customize the header section:
+
+```js
+{
+  llmsTxtHeader: {
+    name: 'My Project',           // defaults to TypeDoc name
+    description: 'A cool library', // defaults to package.json description
+    features: [                    // defaults to empty
+      'Feature one',
+      'Feature two',
+    ],
+  },
+}
+```
+
+### `llmsTxtSections`
+
+Control how document categories are displayed and ordered:
+
+```js
+{
+  llmsTxtSections: {
+    Guides: { displayName: 'Documentation', order: 1 },
+    Reference: { displayName: 'Reference', order: 2 },
+    About: { displayName: 'Optional', order: 3 },
+  },
+}
+```
+
+Categories not listed use their original name and appear alphabetically after configured sections.
+
+### `llmsTxtDeclarations`
+
+Add links to specific API symbols using TypeDoc declaration references:
+
+```js
+{
+  llmsTxtDeclarations: [
+    { ref: 'myproject!', label: 'API Reference', description: 'Full API docs' },
+    { ref: 'myproject!myFunction', label: 'myFunction()' },
+  ],
+}
+```
+
+### `llmsTxtQuickReference`
+
+Add a code examples section:
+
+```js
+{
+  llmsTxtQuickReference: `
+// Basic usage
+import { foo } from 'myproject';
+foo();
+`,
+}
+```
+
+### `llmsTxtTemplate`
+
+Use a custom template file for full layout control:
+
+```js
+{
+  llmsTxtTemplate: './llms-template.md',
+}
+```
+
+Template slots:
+
+- `{{header}}` - Name, description, and features
+- `{{sections}}` - All document sections
+- `{{section:CategoryName}}` - Specific category
+- `{{declarations}}` - API links
+- `{{quickReference}}` - Code examples
+
+## License
+
+[BlueOak-1.0.0](https://blueoakcouncil.org/license/1.0.0)

package/dist/generator.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Core llms.txt content generation logic
+ *
+ * @packageDocumentation
+ */
+import type { Application, ProjectReflection } from 'typedoc';
+import type { LlmsTxtDeclaration, LlmsTxtHeader, LlmsTxtSectionConfig } from './options.js';
+/**
+ * Document info extracted from markdown frontmatter
+ */
+export interface DocumentInfo {
+    category: string;
+    path: string;
+    title: string;
+}
+/**
+ * All content needed to render llms.txt
+ */
+export interface LlmsTxtContent {
+    declarations: ResolvedDeclaration[];
+    header: {
+        description: string;
+        features: string[];
+        name: string;
+    };
+    quickReference: string;
+    sections: Section[];
+}
+/**
+ * Resolved declaration with URL
+ */
+export interface ResolvedDeclaration {
+    description?: string;
+    label: string;
+    url: string;
+}
+/**
+ * Section with its documents
+ */
+export interface Section {
+    displayName: string;
+    documents: DocumentInfo[];
+    name: string;
+    order: number;
+}
+/**
+ * Strips YAML string quotes from a value
+ *
+ * YAML allows strings to be quoted with single or double quotes to escape
+ * special characters. This function removes those quotes to get the actual
+ * string value.
+ *
+ * @function
+ * @param value - Raw YAML string value (may include quotes)
+ * @returns Unquoted string value
+ */
+export declare const stripYamlQuotes: (value: string) => string;
+/**
+ * Extracts YAML frontmatter from markdown content
+ *
+ * @function
+ * @param content - Markdown file content
+ * @returns Frontmatter object or null if not found
+ */
+export declare const extractFrontmatter: (content: string) => null | {
+    category?: string;
+    title?: string;
+};
+/**
+ * Converts a document title to TypeDoc's URL path format
+ *
+ * TypeDoc converts titles by:
+ *
+ * - `@` → `-I_`
+ * - `/` → `_`
+ * - `&` → `___`
+ * - ` ` → `_`
+ *
+ * @function
+ * @param title - Document title
+ * @returns URL path segment
+ */
+export declare const titleToUrlPath: (title: string) => string;
+/**
+ * Discovers sections from project documents
+ *
+ * @function
+ * @param projectDocuments - Paths to project document files
+ * @param sectionConfig - User-provided section configuration
+ * @param baseUrl - Base URL for links
+ * @returns Array of sections with their documents
+ */
+export declare const discoverSections: (projectDocuments: string[], sectionConfig: Record<string, LlmsTxtSectionConfig>, baseUrl: string) => Section[];
+/**
+ * Auto-generates declarations from entry points
+ *
+ * @function
+ * @param project - TypeDoc project reflection
+ * @param baseUrl - Base URL for links
+ * @returns Array of resolved declarations
+ */
+export declare const autoGenerateDeclarations: (project: ProjectReflection, baseUrl: string) => ResolvedDeclaration[];
+/**
+ * Resolves declaration references to URLs
+ *
+ * @function
+ * @param declarations - User-provided declaration configs
+ * @param project - TypeDoc project reflection
+ * @param app - TypeDoc application
+ * @param baseUrl - Base URL for links
+ * @returns Array of resolved declarations
+ */
+export declare const resolveDeclarations: (declarations: LlmsTxtDeclaration[], project: ProjectReflection, app: Application, baseUrl: string) => ResolvedDeclaration[];
+/**
+ * Gets the project name with fallback
+ *
+ * @function
+ * @param app - TypeDoc application
+ * @param headerConfig - User header configuration
+ * @returns Project name
+ */
+export declare const getProjectName: (app: Application, headerConfig: LlmsTxtHeader) => string;
+/**
+ * Gets the project description with fallback to package.json
+ *
+ * @function
+ * @param app - TypeDoc application
+ * @param headerConfig - User header configuration
+ * @returns Project description or empty string
+ */
+export declare const getProjectDescription: (app: Application, headerConfig: LlmsTxtHeader) => string;
+/**
+ * Renders the llms.txt content to a string
+ *
+ * @function
+ * @param content - The content to render
+ * @returns Rendered llms.txt string
+ */
+export declare const renderLlmsTxt: (content: LlmsTxtContent) => string;
+/**
+ * Renders a specific section to markdown
+ *
+ * @function
+ * @param section - The section to render
+ * @returns Rendered section string
+ */
+export declare const renderSection: (section: Section) => string;
+/**
+ * Renders the header to markdown
+ *
+ * @function
+ * @param header - Header content
+ * @returns Rendered header string
+ */
+export declare const renderHeader: (header: LlmsTxtContent["header"]) => string;
+/**
+ * Renders declarations to markdown
+ *
+ * @function
+ * @param declarations - Resolved declarations
+ * @returns Rendered declarations string
+ */
+export declare const renderDeclarations: (declarations: ResolvedDeclaration[]) => string;
+/**
+ * Renders quick reference to markdown
+ *
+ * @function
+ * @param quickReference - Quick reference content
+ * @returns Rendered quick reference string
+ */
+export declare const renderQuickReference: (quickReference: string) => string;
+//# sourceMappingURL=generator.d.ts.map

package/dist/generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generator.d.ts","sourceRoot":"","sources":["../src/generator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAK9D,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACb,oBAAoB,EACrB,MAAM,cAAc,CAAC;AAEtB;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,mBAAmB,EAAE,CAAC;IACpC,MAAM,EAAE;QACN,WAAW,EAAE,MAAM,CAAC;QACpB,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,YAAY,EAAE,CAAC;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,eAAe,GAAI,OAAO,MAAM,KAAG,MAc/C,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,SAAS,MAAM,KACd,IAAI,GAAG;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAoB5C,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,MAAM,KAAG,MAM9C,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,GAC3B,kBAAkB,MAAM,EAAE,EAC1B,eAAe,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,EACnD,SAAS,MAAM,KACd,OAAO,EAsDT,CAAC;AAcF;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,iBAAiB,EAC1B,SAAS,MAAM,KACd,mBAAmB,EAkBrB,CAAC;AAuCF;;;;;;;;;GASG;AACH,eAAO,MAAM,mBAAmB,GAC9B,cAAc,kBAAkB,EAAE,EAClC,SAAS,iBAAiB,EAC1B,KAAK,WAAW,EAChB,SAAS,MAAM,KACd,mBAAmB,EA+DrB,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,GACzB,KAAK,WAAW,EAChB,cAAc,aAAa,KAC1B,MAKF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,qBAAqB,GAChC,KAAK,WAAW,EAChB,cAAc,aAAa,KAC1B,MAgBF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,cAAc,KAAG,MAmDvD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,GAAI,SAAS,OAAO,KAAG,MAOhD,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,QAAQ,cAAc,CAAC,QAAQ,CAAC,KAAG,MAiB/D,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,GAC7B,cAAc,mBAAmB,EAAE,KAClC,MAeF,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,gBAAgB,MAAM,KAAG,MAY7D,CAAC"}