rspress-plugin-api-extractor 0.1.2 → 0.2.1

package/og-resolver.js

@@ -0,0 +1,271 @@
+import fs from "node:fs";
+import path from "node:path";
+import { imageSizeFromFile } from "image-size/fromFile";
+
+//#region src/og-resolver.ts
+/**
+* MIME type mappings for common image formats.
+* Used to determine the `og:image:type` meta tag value.
+*/
+const IMAGE_MIME_TYPES = {
+	jpg: "image/jpeg",
+	jpeg: "image/jpeg",
+	png: "image/png",
+	gif: "image/gif",
+	webp: "image/webp",
+	svg: "image/svg+xml"
+};
+/**
+* Resolves Open Graph image configurations into fully-qualified metadata.
+*
+* This class handles the conversion of flexible OG image configuration formats
+* (strings or metadata objects) into complete `OpenGraphImageMetadata` objects
+* with resolved URLs and auto-detected dimensions for local images.
+*
+* @remarks
+* The resolver supports two input formats:
+* - **String format**: A URL or path that will be resolved and optionally enhanced
+*   with auto-detected dimensions if pointing to a local file.
+* - **Object format**: Detailed metadata with explicit properties that will be
+*   validated and URL-resolved.
+*
+* @example Basic usage with a relative path
+* ```typescript
+* const resolver = new OpenGraphResolver({
+*   siteUrl: "https://example.com",
+*   docsRoot: "/path/to/docs"
+* });
+*
+* const metadata = await resolver.resolve(
+*   "/images/og-api.png",
+*   "my-package",
+*   "MyClass"
+* );
+* // Result: { url: "https://example.com/images/og-api.png", width: 1200, height: 630, ... }
+* ```
+*
+* @example Using detailed configuration
+* ```typescript
+* const metadata = await resolver.resolve(
+*   {
+*     url: "/images/og.png",
+*     alt: "Custom alt text",
+*     width: 1200,
+*     height: 630
+*   },
+*   "my-package"
+* );
+* ```
+*/
+var OpenGraphResolver = class {
+	siteUrl;
+	docsRoot;
+	/**
+	* Creates a new OpenGraphResolver instance.
+	*
+	* @param options - Configuration options for the resolver.
+	*   `siteUrl`: Base URL for the website (e.g., "https://example.com"),
+	*   used to construct absolute URLs from relative paths.
+	*   `docsRoot`: Optional root directory for documentation files;
+	*   when provided, enables auto-detection of image dimensions for local files
+	*   by looking in the `public` subdirectory.
+	*/
+	constructor(options) {
+		this.siteUrl = options.siteUrl;
+		if (options.docsRoot != null) this.docsRoot = options.docsRoot;
+	}
+	/**
+	* Resolves an Open Graph image configuration into complete metadata.
+	*
+	* Handles both string URLs/paths and detailed metadata objects, converting them
+	* into fully-qualified `OpenGraphImageMetadata` with absolute URLs.
+	*
+	* @param config - The OG image configuration to resolve. Can be:
+	*   - A string URL (absolute or relative path starting with `/`)
+	*   - An `OpenGraphImageMetadata` object with explicit properties
+	*   - `undefined` to indicate no OG image
+	* @param packageName - The package name for generating default alt text
+	* @param apiName - Optional API name for more descriptive alt text
+	* @returns Resolved metadata with absolute URLs, or `undefined` if:
+	*   - `config` is `undefined`
+	*   - The URL format is invalid
+	*
+	* @example Resolve a relative path
+	* ```typescript
+	* const metadata = await resolver.resolve("/images/og.png", "my-lib");
+	* // Returns: { url: "https://example.com/images/og.png", alt: "my-lib API Documentation", ... }
+	* ```
+	*
+	* @example Resolve an absolute URL
+	* ```typescript
+	* const metadata = await resolver.resolve("https://cdn.example.com/og.png", "my-lib");
+	* // Returns: { url: "https://cdn.example.com/og.png", alt: "my-lib API Documentation" }
+	* ```
+	*/
+	async resolve(config, packageName, apiName) {
+		if (!config) return;
+		if (typeof config === "object") return this.resolveFromMetadata(config, packageName, apiName);
+		return this.resolveFromString(config, packageName, apiName);
+	}
+	/**
+	* Resolves a metadata object configuration into complete OG image metadata.
+	*
+	* Validates and resolves URLs in the provided metadata object, ensuring all
+	* URLs are absolute and properly formatted.
+	*
+	* @param metadata - The metadata object containing OG image properties
+	* @param packageName - Package name for default alt text generation
+	* @param apiName - Optional API name for more descriptive alt text
+	* @returns Resolved metadata with absolute URLs, or `undefined` if URL is invalid
+	*/
+	async resolveFromMetadata(metadata, packageName, apiName) {
+		const { url, secureUrl, type, width, height, alt } = metadata;
+		const resolvedUrl = this.resolveUrl(url);
+		if (!resolvedUrl) {
+			console.warn(`[og-resolver] Invalid ogImage URL format: "${url}"`);
+			return;
+		}
+		let resolvedSecureUrl;
+		if (secureUrl) if (secureUrl.startsWith("https://")) resolvedSecureUrl = secureUrl;
+		else console.warn(`[og-resolver] ogImage secureUrl must be an absolute HTTPS URL: "${secureUrl}"`);
+		return {
+			url: resolvedUrl,
+			secureUrl: resolvedSecureUrl,
+			type,
+			width,
+			height,
+			alt: alt ?? this.generateAltText(packageName, apiName)
+		};
+	}
+	/**
+	* Resolves a string URL/path into complete OG image metadata.
+	*
+	* For relative paths pointing to local files, this method will attempt to:
+	* 1. Locate the file in the docs `public` directory
+	* 2. Read the image dimensions using `image-size`
+	* 3. Determine the MIME type from the file extension
+	*
+	* @param imageUrl - The image URL or path to resolve
+	* @param packageName - Package name for alt text generation
+	* @param apiName - Optional API name for more descriptive alt text
+	* @returns Resolved metadata with auto-detected dimensions for local files,
+	*   or `undefined` if the URL format is invalid
+	*/
+	async resolveFromString(imageUrl, packageName, apiName) {
+		const resolvedUrl = this.resolveUrl(imageUrl);
+		if (!resolvedUrl) {
+			console.warn(`[og-resolver] Invalid ogImage format: "${imageUrl}" (must be absolute URL or path starting with /)`);
+			return;
+		}
+		const localPath = this.findLocalImage(imageUrl);
+		const dimensions = localPath ? await this.readImageDimensions(localPath) : void 0;
+		return {
+			url: resolvedUrl,
+			type: dimensions?.type,
+			width: dimensions?.width,
+			height: dimensions?.height,
+			alt: this.generateAltText(packageName, apiName)
+		};
+	}
+	/**
+	* Resolves a URL string to an absolute URL.
+	*
+	* @param url - The URL to resolve (absolute URL or relative path)
+	* @returns The absolute URL, or `undefined` if the format is invalid
+	*/
+	resolveUrl(url) {
+		if (url.startsWith("http://") || url.startsWith("https://")) return url;
+		if (url.startsWith("/")) return `${this.siteUrl}${url}`;
+	}
+	/**
+	* Attempts to find a local image file in the docs public directory.
+	*
+	* @param imagePath - The relative image path (starting with `/`)
+	* @returns The absolute file path if found, or `undefined` if not found
+	*   or if `docsRoot` is not configured
+	*/
+	findLocalImage(imagePath) {
+		if (!this.docsRoot || !imagePath.startsWith("/")) return;
+		const publicPath = path.join(this.docsRoot, "public", imagePath);
+		if (fs.existsSync(publicPath)) return publicPath;
+	}
+	/**
+	* Reads image dimensions and type from a local file.
+	*
+	* @param filePath - Absolute path to the image file
+	* @returns Object containing width, height, and MIME type if successful,
+	*   or `undefined` if the file cannot be read or analyzed
+	*/
+	async readImageDimensions(filePath) {
+		try {
+			const dimensions = await imageSizeFromFile(filePath);
+			let mimeType;
+			if (dimensions.type) mimeType = IMAGE_MIME_TYPES[dimensions.type.toLowerCase()];
+			return {
+				width: dimensions.width,
+				height: dimensions.height,
+				...mimeType != null ? { type: mimeType } : {}
+			};
+		} catch (error) {
+			console.warn(`[og-resolver] Failed to read image dimensions from ${filePath}:`, error.message);
+			return;
+		}
+	}
+	/**
+	* Generates descriptive alt text for the OG image.
+	*
+	* @param packageName - The package name
+	* @param apiName - Optional API name for more specific text
+	* @returns Generated alt text string
+	*/
+	generateAltText(packageName, apiName) {
+		if (apiName) return `${apiName} - ${packageName} API Documentation`;
+		return `${packageName} API Documentation`;
+	}
+	/**
+	* Creates complete Open Graph metadata for an API documentation page.
+	*
+	* This static factory method builds a complete `OpenGraphMetadata` object
+	* suitable for inclusion in page frontmatter, combining resolved image
+	* metadata with article-specific information.
+	*
+	* @param options - Configuration for the OG metadata.
+	*   Includes `siteUrl`, `pageRoute`, `description`, `publishedTime`,
+	*   `modifiedTime`, `section`, `packageName`, and optional `ogImage`.
+	* @returns Complete Open Graph metadata object
+	*
+	* @example
+	* ```typescript
+	* const ogMetadata = OpenGraphResolver.createPageMetadata({
+	*   siteUrl: "https://example.com",
+	*   pageRoute: "/api/classes/MyClass",
+	*   description: "MyClass provides...",
+	*   publishedTime: "2024-01-15T10:00:00Z",
+	*   modifiedTime: "2024-01-20T15:30:00Z",
+	*   section: "Classes",
+	*   packageName: "my-library",
+	*   ogImage: resolvedImageMetadata
+	* });
+	* ```
+	*/
+	static createPageMetadata(options) {
+		return {
+			siteUrl: options.siteUrl,
+			pageRoute: options.pageRoute,
+			description: options.description,
+			publishedTime: options.publishedTime,
+			modifiedTime: options.modifiedTime,
+			section: options.section,
+			tags: [
+				"TypeScript",
+				"API",
+				options.packageName
+			],
+			...options.ogImage != null ? { ogImage: options.ogImage } : {},
+			ogType: "article"
+		};
+	}
+};
+
+//#endregion
+export { OpenGraphResolver };

package/package.json

@@ -1,75 +1,66 @@
 {
-  "name": "rspress-plugin-api-extractor",
-  "version": "0.1.2",
-  "private": false,
-  "description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
-  "keywords": [
-    "rspress",
-    "plugin",
-    "api-extractor",
-    "documentation",
-    "typescript"
-  ],
-  "homepage": "https://github.com/spencerbeggs/rspress-plugin-api-extractor#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/spencerbeggs/rspress-plugin-api-extractor.git",
-    "directory": "plugin"
-  },
-  "license": "MIT",
-  "author": "Spencer Beggs",
-  "type": "module",
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "import": "./index.js"
-    },
-    "./runtime": {
-      "types": "./runtime/index.d.ts",
-      "import": "./runtime/index.js"
-    }
-  },
-  "files": [
-    "!rspress-plugin-api-extractor.api.json",
-    "!tsconfig.json",
-    "!tsdoc.json",
-    "0~llms-program.js",
-    "LICENSE",
-    "README.md",
-    "index.d.ts",
-    "index.js",
-    "package.json",
-    "runtime",
-    "tsdoc-metadata.json"
-  ],
-  "dependencies": {
-    "@effect/platform": "^0.96.1",
-    "@effect/platform-node": "^0.106.0",
-    "@effect/sql": "^0.51.1",
-    "@effect/sql-sqlite-node": "^0.52.0",
-    "@microsoft/api-extractor-model": "^7.33.8",
-    "@shikijs/twoslash": "^4.1.0",
-    "api-extractor-llms": "0.1.0",
-    "clsx": "^2.1.1",
-    "effect": "^3.21.2",
-    "gray-matter": "^4.0.3",
-    "hast-util-to-jsx-runtime": "^2.3.6",
-    "image-size": "^2.0.2",
-    "mdast-util-from-markdown": "^2.0.3",
-    "mdast-util-to-hast": "^13.2.1",
-    "prettier": "^3.8.3",
-    "react-markdown": "^10.1.0",
-    "semver-effect": "^0.2.1",
-    "shiki": "^4.1.0",
-    "type-registry-effect": "^0.2.3",
-    "typescript": "^6.0.3"
-  },
-  "peerDependencies": {
-    "@rspress/core": "^2.0.0",
-    "react": "^19.2.0",
-    "react-dom": "^19.2.0"
-  },
-  "engines": {
-    "node": ">=24.1.0"
-  }
+	"name": "rspress-plugin-api-extractor",
+	"version": "0.2.1",
+	"private": false,
+	"description": "RSPress plugin for generating API documentation from TypeScript API Extractor models",
+	"keywords": [
+		"rspress",
+		"plugin",
+		"api-extractor",
+		"documentation",
+		"typescript"
+	],
+	"homepage": "https://github.com/spencerbeggs/rspress-plugin-api-extractor#readme",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/rspress-plugin-api-extractor.git",
+		"directory": "plugin"
+	},
+	"license": "MIT",
+	"author": "Spencer Beggs",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js"
+		},
+		"./runtime": {
+			"types": "./runtime/index.d.ts",
+			"import": "./runtime/index.js"
+		},
+		"./tsconfig/rspress.json": "./public/tsconfig/rspress.json",
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@effect/platform": "^0.96.1",
+		"@effect/platform-node": "^0.107.0",
+		"@effect/sql": "^0.51.1",
+		"@effect/sql-sqlite-node": "^0.52.0",
+		"@microsoft/api-extractor-model": "^7.33.8",
+		"@shikijs/twoslash": "^4.1.0",
+		"api-extractor-llms": "0.1.0",
+		"clsx": "^2.1.1",
+		"effect": "^3.21.3",
+		"gray-matter": "^4.0.3",
+		"hast-util-to-jsx-runtime": "^2.3.6",
+		"image-size": "^2.0.2",
+		"mdast-util-from-markdown": "^2.0.3",
+		"mdast-util-to-hast": "^13.2.1",
+		"open": "^11.0.0",
+		"prettier": "^3.8.3",
+		"react-markdown": "^10.1.0",
+		"semver-effect": "^0.2.1",
+		"shiki": "^4.1.0",
+		"type-registry-effect": "^0.2.3",
+		"typescript": "^6.0.3",
+		"unist-util-visit": "^5.1.0"
+	},
+	"peerDependencies": {
+		"@rspress/core": "^2.0.0",
+		"react": "^19.2.0",
+		"react-dom": "^19.2.0"
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
 }

package/path-derivation.js

@@ -0,0 +1,48 @@
+import path from "node:path";
+
+//#region src/path-derivation.ts
+/** Extract unscoped name from a potentially scoped package name */
+function unscopedName(packageName) {
+	return packageName.startsWith("@") ? packageName.split("/")[1] ?? packageName : packageName;
+}
+/** Normalize baseRoute: ensure leading slash, strip trailing slash, preserve root "/" */
+function normalizeBaseRoute(route) {
+	const withSlash = route.startsWith("/") ? route : `/${route}`;
+	const stripped = withSlash.endsWith("/") ? withSlash.slice(0, -1) : withSlash;
+	return stripped === "" ? "/" : stripped;
+}
+function deriveOutputPaths(input) {
+	const { docsRoot, baseRoute, apiFolder, locales, defaultLang, versions, defaultVersion } = input;
+	const results = [];
+	const folder = apiFolder ?? void 0;
+	const baseSegment = baseRoute === "/" ? void 0 : baseRoute.replace(/^\//, "");
+	const versionList = versions.length > 0 ? versions : [void 0];
+	const localeList = locales.length > 0 ? locales : [void 0];
+	for (const version of versionList) for (const locale of localeList) {
+		const dirParts = [
+			docsRoot,
+			version,
+			locale,
+			baseSegment,
+			folder
+		].filter((p) => p !== void 0);
+		const outputDir = dirParts.length > 0 ? path.join(...dirParts) : docsRoot;
+		const routeParts = [
+			!(version === defaultVersion) ? version : void 0,
+			!(locale === defaultLang) ? locale : void 0,
+			baseSegment,
+			folder
+		].filter((p) => p !== void 0);
+		const routeBase = routeParts.length > 0 ? `/${routeParts.join("/")}` : "/";
+		results.push({
+			outputDir,
+			routeBase,
+			version,
+			locale
+		});
+	}
+	return results;
+}
+
+//#endregion
+export { deriveOutputPaths, normalizeBaseRoute, unscopedName };

package/plugin.js

@@ -0,0 +1,218 @@
+import { PluginLoggerLayer, logBuildSummary } from "./layers/ObservabilityLive.js";
+import { TwoslashManager } from "./twoslash-transformer.js";
+import { VfsRegistry } from "./vfs-registry.js";
+import { generateApiDocs } from "./build-program.js";
+import { deriveOutputPaths, normalizeBaseRoute, unscopedName } from "./path-derivation.js";
+import { fromDir, fromParentDir } from "./config-helpers.js";
+import { mergeLlmsPluginConfig } from "./config-utils.js";
+import { DEFAULT_SHIKI_THEMES } from "./markdown/shiki-utils.js";
+import { PluginOptions } from "./schemas/config.js";
+import "./schemas/index.js";
+import { ConfigService } from "./services/ConfigService.js";
+import { ConfigServiceLive } from "./layers/ConfigServiceLive.js";
+import { PathDerivationServiceLive } from "./layers/PathDerivationServiceLive.js";
+import { SnapshotServiceLive } from "./layers/SnapshotServiceLive.js";
+import { TypeRegistryServiceLive } from "./layers/TypeRegistryServiceLive.js";
+import { remarkApiCodeblocks } from "./remark-api-codeblocks.js";
+import { remarkWithApi } from "./remark-with-api.js";
+import { ShikiCrossLinker } from "./shiki-transformer.js";
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { NodeFileSystem } from "@effect/platform-node";
+import { Effect, Layer, ManagedRuntime, Schema } from "effect";
+
+//#region src/plugin.ts
+/* v8 ignore start -- RSPress plugin adapter, requires RSPress runtime */
+/**
+* Normalize theme configuration from user input to a consistent format.
+*/
+function normalizeThemeConfig(theme) {
+	if (!theme) return { ...DEFAULT_SHIKI_THEMES };
+	if (typeof theme === "string") return {
+		light: theme,
+		dark: theme
+	};
+	if ("light" in theme && "dark" in theme && typeof theme.light === "string" && typeof theme.dark === "string") return {
+		light: theme.light,
+		dark: theme.dark
+	};
+	return {
+		light: theme,
+		dark: theme
+	};
+}
+/**
+* RSPress plugin for generating API documentation from API Extractor model files
+*/
+function ApiExtractorPluginImpl(rawOptions) {
+	const options = Schema.decodeUnknownSync(PluginOptions)(rawOptions);
+	const shikiCrossLinker = new ShikiCrossLinker();
+	const logLevel = process.env.LOG_LEVEL?.toLowerCase() || options.logLevel || "info";
+	const dbPath = path.resolve(process.cwd(), "api-docs-snapshot.db");
+	const BaseLayer = Layer.mergeAll(PathDerivationServiceLive, PluginLoggerLayer(logLevel), TypeRegistryServiceLive, NodeFileSystem.layer, SnapshotServiceLive(dbPath));
+	const EffectAppLayer = Layer.provideMerge(ConfigServiceLive(options, shikiCrossLinker), BaseLayer);
+	const effectRuntime = ManagedRuntime.make(EffectAppLayer);
+	const fileContextMap = /* @__PURE__ */ new Map();
+	const isVerbose = logLevel === "verbose" || logLevel === "debug";
+	let docsRoot;
+	let isFirstBuild = true;
+	let rspressLlmsEnabled = false;
+	let rspressOutDir = "dist";
+	const buildResults = [];
+	const resolvedLlmsPlugin = mergeLlmsPluginConfig(options.llmsPlugin);
+	const packageRoutes = /* @__PURE__ */ new Map();
+	return {
+		name: "rspress-plugin-api-docs",
+		async beforeBuild(_config, _isProd) {},
+		async afterBuild(_config, isProd) {
+			if (isFirstBuild) {
+				await effectRuntime.runPromise(logBuildSummary);
+				if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled) {
+					const { processLlmsFiles } = await import("./llms-program.js");
+					await effectRuntime.runPromise(processLlmsFiles({
+						outDir: path.resolve(process.cwd(), rspressOutDir),
+						buildResults,
+						llmsPlugin: resolvedLlmsPlugin,
+						packageRoutes
+					}));
+				}
+				isFirstBuild = false;
+			}
+			if (isProd) await effectRuntime.dispose();
+		},
+		async config(_config) {
+			const buildStartTime = performance.now();
+			if (_config.root) docsRoot = path.isAbsolute(_config.root) ? _config.root : path.resolve(process.cwd(), _config.root);
+			const rspressRoot = docsRoot || process.cwd();
+			const rspressLocales = _config.locales?.map((l) => l.lang) ?? [];
+			const rspressLang = _config.lang;
+			const rspressMultiVersion = _config.multiVersion;
+			rspressLlmsEnabled = Boolean(_config.llms);
+			rspressOutDir = _config.outDir ?? "dist";
+			if (options.api) {
+				const api = options.api;
+				const baseRoute = normalizeBaseRoute(api.baseRoute ?? "/");
+				const versions = rspressMultiVersion?.versions ?? [];
+				const derivedPaths = deriveOutputPaths({
+					mode: "single",
+					docsRoot: rspressRoot,
+					baseRoute,
+					apiFolder: api.apiFolder ?? "api",
+					locales: rspressLocales,
+					defaultLang: rspressLang,
+					versions,
+					defaultVersion: rspressMultiVersion?.default
+				});
+				for (const dp of derivedPaths) fs.mkdirSync(dp.outputDir, { recursive: true });
+			} else if (options.apis) for (const api of options.apis) {
+				const derivedPaths = deriveOutputPaths({
+					mode: "multi",
+					docsRoot: rspressRoot,
+					baseRoute: normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`),
+					apiFolder: api.apiFolder ?? "api",
+					locales: rspressLocales,
+					defaultLang: rspressLang,
+					versions: [],
+					defaultVersion: void 0
+				});
+				for (const dp of derivedPaths) fs.mkdirSync(dp.outputDir, { recursive: true });
+			}
+			VfsRegistry.clear();
+			fileContextMap.clear();
+			if (isVerbose) console.log("🚀 RSPress API Extractor Plugin");
+			try {
+				const rspressConfigSubset = {
+					...rspressMultiVersion != null ? { multiVersion: rspressMultiVersion } : {},
+					...rspressLocales.length > 0 ? { locales: rspressLocales.map((lang) => ({ lang })) } : {},
+					...rspressLang != null ? { lang: rspressLang } : {},
+					...docsRoot != null ? { root: docsRoot } : {}
+				};
+				await effectRuntime.runPromise(Effect.gen(function* () {
+					const buildContext = yield* (yield* ConfigService).resolve(rspressConfigSubset);
+					yield* Effect.logInfo("Generating API documentation...");
+					buildResults.length = 0;
+					yield* Effect.forEach(buildContext.apiConfigs, (apiConfig) => generateApiDocs({
+						...apiConfig,
+						suppressExampleErrors: buildContext.suppressExampleErrors
+					}, buildContext, fileContextMap).pipe(Effect.tap((result) => {
+						buildResults.push(result);
+						return Effect.void;
+					}), Effect.tap(() => isVerbose ? Effect.logDebug(`Generating docs for ${apiConfig.packageName}`) : Effect.void)), { concurrency: 2 });
+				}).pipe(Effect.scoped));
+				if (logLevel !== "none") {
+					const totalTime = ((performance.now() - buildStartTime) / 1e3).toFixed(2);
+					console.log(`✅ API documentation complete (${totalTime}s)`);
+				}
+			} catch (error) {
+				console.error(`❌ Error generating API documentation: ${error instanceof Error ? error.message : String(error)}`);
+				throw error;
+			}
+			const updatedConfig = { ..._config };
+			if (!updatedConfig.builderConfig) updatedConfig.builderConfig = {};
+			if (!updatedConfig.builderConfig.source) updatedConfig.builderConfig.source = {};
+			if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
+				if (!updatedConfig.builderConfig.resolve) updatedConfig.builderConfig.resolve = {};
+				const pluginDir = path.dirname(fileURLToPath(import.meta.url));
+				const customLlmsViewOptions = path.resolve(pluginDir, "runtime/components/ApiLlmsViewOptions/index.js");
+				const pluginRequire = createRequire(import.meta.url);
+				const rspressCoreDir = path.dirname(pluginRequire.resolve("@rspress/core/package.json"));
+				const originalLlmsViewOptions = path.join(rspressCoreDir, "dist/theme/components/Llms/LlmsViewOptions.js");
+				const existingAlias = updatedConfig.builderConfig.resolve.alias;
+				updatedConfig.builderConfig.resolve.alias = {
+					...typeof existingAlias === "object" && existingAlias !== null ? existingAlias : {},
+					[originalLlmsViewOptions]: customLlmsViewOptions
+				};
+			}
+			const existingInclude = updatedConfig.builderConfig.source.include || [];
+			if (!existingInclude.includes("rspress-plugin-api-extractor/runtime")) updatedConfig.builderConfig.source.include = [...existingInclude, "rspress-plugin-api-extractor/runtime"];
+			if (!updatedConfig.markdown) updatedConfig.markdown = {};
+			if (!updatedConfig.markdown.remarkPlugins) updatedConfig.markdown.remarkPlugins = [];
+			const remarkTheme = normalizeThemeConfig(options.api?.theme ?? options.apis?.[0]?.theme);
+			updatedConfig.markdown.remarkPlugins.push([remarkWithApi, {
+				shikiCrossLinker,
+				getTransformer: () => TwoslashManager.getInstance().getTransformer(),
+				theme: remarkTheme
+			}]);
+			updatedConfig.markdown.remarkPlugins.push([remarkApiCodeblocks]);
+			if (rspressLlmsEnabled && resolvedLlmsPlugin.enabled && resolvedLlmsPlugin.scopes) {
+				packageRoutes.clear();
+				if (options.api) packageRoutes.set(options.api.packageName, normalizeBaseRoute(options.api.baseRoute ?? "/"));
+				else if (options.apis) for (const api of options.apis) packageRoutes.set(api.packageName, normalizeBaseRoute(api.baseRoute ?? `/${unscopedName(api.packageName)}`));
+				const scopes = buildResults.map((result) => ({
+					name: result.apiName ?? result.packageName,
+					packageName: result.packageName,
+					packageRoute: packageRoutes.get(result.packageName) ?? result.baseRoute,
+					baseRoute: result.baseRoute,
+					version: null,
+					locale: null,
+					llmsTxt: `${packageRoutes.get(result.packageName) ?? result.baseRoute}/llms.txt`,
+					llmsFullTxt: `${packageRoutes.get(result.packageName) ?? result.baseRoute}/llms-full.txt`,
+					llmsDocsTxt: `${packageRoutes.get(result.packageName) ?? result.baseRoute}/llms-docs.txt`,
+					llmsApiTxt: resolvedLlmsPlugin.apiTxt ? `${packageRoutes.get(result.packageName) ?? result.baseRoute}/llms-api.txt` : null
+				}));
+				if (!updatedConfig.themeConfig) updatedConfig.themeConfig = {};
+				updatedConfig.themeConfig.apiExtractorScopes = scopes;
+				if (!updatedConfig.globalUIComponents) updatedConfig.globalUIComponents = [];
+				const llmsComponentPluginDir = path.dirname(fileURLToPath(import.meta.url));
+				const llmsComponentPath = path.resolve(llmsComponentPluginDir, "runtime/components/ApiLlmsPackageActions/index.js");
+				updatedConfig.globalUIComponents.push(llmsComponentPath);
+			}
+			return updatedConfig;
+		}
+	};
+}
+/**
+* RSPress plugin for generating API documentation from API Extractor model
+* files. Config helpers are available under `ApiExtractorPlugin.api` (single
+* package → one config for the `api:` option) and `ApiExtractorPlugin.apis`
+* (parent directory → array for the `apis:` option).
+*/
+const ApiExtractorPlugin = Object.assign(ApiExtractorPluginImpl, {
+	api: { fromDir },
+	apis: { fromDir: fromParentDir }
+});
+
+//#endregion
+export { ApiExtractorPlugin };