vitepress-api-references 0.0.0 → 0.1.0

package/README.md

@@ -2,9 +2,81 @@
 
 [![npm][npm-src]][npm-href] [![CI][ci-src]][ci-href]
 
-> [!WARNING] WIP
+Enable JSDoc API Reference for VitePress.
 
-Enable JSDoc API Reference.
+## Usage
+
+### VitePress integration
+
+This repository uses the VitePress integration to generate and serve its own API reference docs. See [`docs/.vitepress/config.ts`](./docs/.vitepress/config.ts) and the generated [`docs/api`](./docs/api) directory for a working self-hosted example.
+
+```ts
+import { defineConfig } from 'vitepress'
+import { withOxContentApiDocs } from 'vitepress-api-references'
+
+export default defineConfig(
+  await withOxContentApiDocs({
+    themeConfig: {
+      sidebar: [{ text: 'Guide', link: '/' }, { text: 'API References' }]
+    },
+    apiDocs: {
+      entryPoints: [{ path: 'src/index.ts', name: 'default' }],
+      outDir: 'docs/api',
+      basePath: '/api',
+      markdown: {
+        pathStrategy: 'typedoc',
+        renderStyle: 'markdown',
+        indexFormat: 'table'
+      },
+      nav: {
+        section: { text: 'API References', collapsed: false },
+        insert: 'replace',
+        replaceText: 'API References'
+      }
+    }
+  })
+)
+```
+
+### Standalone markdown generation
+
+Use `generateOxContentApiDocs` when you want to generate markdown files directly without wiring the result into VitePress. See [`standalone/generate.ts`](./standalone/generate.ts) for a runnable example.
+
+```ts
+import { generateOxContentApiDocs } from 'vitepress-api-references'
+
+const result = await generateOxContentApiDocs({
+  entryPoints: [{ path: 'src/index.ts', name: 'default' }],
+  outDir: 'standalone',
+  basePath: '/standalone',
+  markdown: {
+    pathStrategy: 'typedoc',
+    renderStyle: 'markdown',
+    indexFormat: 'table'
+  }
+})
+
+console.log(`Generated ${result.generatedFiles.length} files`)
+```
+
+Run the example with:
+
+```sh
+vp run docs:standalone
+```
+
+## Local API reference docs
+
+This repository uses its own public root API as the docs source under `docs/`.
+
+```sh
+vp run docs:build
+vp run docs:dev
+```
+
+## Credits
+
+Built on top of [Ox Content](https://github.com/ubugeeei-prod/ox-content), which extracts JSDoc API metadata and renders the generated markdown.
 
 ## License
 

package/dist/index.d.mts

@@ -1,9 +1,385 @@
-//#region src/index.d.ts
+import { JsDocsMarkdownModule, JsDocsMarkdownOptions, JsEntryPointDocsOptions, JsEntryPointSpec, JsExternalPackageSource } from "@ox-content/napi";
+import { UserConfig } from "vitepress";
+
+//#region src/types.d.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+type EntryPointInput = string | {
+  path: string | URL;
+  name?: string;
+};
+interface ExternalPackageSourceInput {
+  /** Package name whose exported docs can be linked from generated references. */
+  package: string;
+  /** Entry point file or URL used to extract metadata for the external package. */
+  entry: string | URL;
+}
+interface VitePressSidebarSectionOptions {
+  /** Label shown for the generated top-level sidebar section. */
+  text: string;
+  /**
+   * Whether the generated top-level sidebar section starts collapsed in VitePress.
+   *
+   * @default undefined
+   */
+  collapsed?: boolean;
+}
+interface ResolvedOxContentExtractionOptions extends Omit<JsEntryPointDocsOptions, 'root' | 'tsconfig'> {
+  /** External package sources converted to the structure expected by ox-content. */
+  externalPackageSources?: JsExternalPackageSource[];
+}
+/** Controls which declarations and metadata ox-content extracts from entry points. */
+interface OxContentExtractionOptions {
+  /**
+   * Include declarations marked as private.
+   *
+   * @default false
+   */
+  private?: boolean;
+  /**
+   * Include declarations marked as internal.
+   *
+   * @default false
+   */
+  internal?: boolean;
+  /**
+   * Preserve external documentation links and metadata from source declarations.
+   *
+   * @default false
+   */
+  externalDocs?: boolean;
+  /**
+   * Include generic type parameter declarations and descriptions in generated docs.
+   *
+   * @default false
+   */
+  typeParameters?: boolean;
+  /**
+   * External packages used to resolve cross-package references in generated docs.
+   *
+   * @default undefined
+   */
+  externalPackageSources?: ExternalPackageSourceInput[];
+}
+/** Markdown rendering options forwarded to ox-content after project defaults are applied. */
+interface OxContentMarkdownOptions extends Omit<JsDocsMarkdownOptions, 'basePath' | 'githubUrl'> {}
+type VitePressSidebarInsert = 'append' | 'prepend' | 'replace' | ((sidebar: unknown, generated: VitePressSidebarItem) => unknown);
+/** Configures generated VitePress sidebar data and optional navigation artifacts. */
+interface VitePressNavOptions {
+  /**
+   * Whether generated navigation integration is enabled.
+   *
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Optional top-level sidebar section that wraps all generated API doc items.
+   *
+   * @default undefined
+   */
+  section?: VitePressSidebarSectionOptions;
+  /**
+   * Positioning strategy used when merging generated items into an existing sidebar.
+   *
+   * @default 'append'
+   */
+  insert?: VitePressSidebarInsert;
+  /**
+   * Sidebar item text to replace when `insert` is set to `replace`.
+   *
+   * @default undefined
+   */
+  replaceText?: string;
+  /**
+   * Route key to update when the existing VitePress sidebar is a route map.
+   *
+   * @default undefined
+   */
+  sidebarRoute?: string;
+  /**
+   * Collapsed state for generated sidebar branches, or a resolver called per item.
+   *
+   * @default undefined
+   */
+  collapsed?: boolean | ((item: ApiDocsNavItem, depth: number) => boolean | undefined);
+  /**
+   * File path for generated navigation code, or `false` to skip writing it.
+   *
+   * @default undefined
+   */
+  outputFile?: string | false;
+  /**
+   * Virtual module id that exposes generated navigation data, or `false` to disable it.
+   *
+   * @default false
+   */
+  virtualModule?: string | false;
+  /**
+   * Named export used in the generated navigation code file.
+   *
+   * @default 'apiDocsNav'
+   */
+  exportName?: string;
+}
+/** User-facing options for generating API reference markdown and VitePress integration. */
+interface OxContentApiDocsOptions {
+  /**
+   * Project root used to resolve relative paths.
+   *
+   * @default process.cwd()
+   */
+  root?: string | URL;
+  /**
+   * TypeScript configuration file used for declaration extraction.
+   *
+   * @default undefined
+   */
+  tsconfig?: string | URL;
+  /** Source entry points whose exported declarations become API docs pages. */
+  entryPoints: EntryPointInput[];
+  /** Directory where generated markdown and optional artifacts are written. */
+  outDir: string | URL;
+  /** Base route used when generating links between API docs pages. */
+  basePath: string;
+  /**
+   * GitHub repository URL used to generate source links for declarations.
+   *
+   * @default undefined
+   */
+  githubUrl?: string;
+  /**
+   * Whether generated output should be cleaned before writing.
+   *
+   * @default undefined
+   */
+  clean?: boolean;
+  /**
+   * Whether generated files and artifacts are written to disk.
+   *
+   * @default true
+   */
+  write?: boolean;
+  /**
+   * Controls which declarations and metadata are extracted from entry points.
+   *
+   * @default {}
+   */
+  extraction?: OxContentExtractionOptions;
+  /**
+   * Controls markdown page generation, grouping, sorting, and rendering details.
+   *
+   * @default {}
+   */
+  markdown?: OxContentMarkdownOptions;
+  /**
+   * Controls generated VitePress sidebar integration and optional nav artifacts.
+   *
+   * @default { enabled: true, insert: 'append', virtualModule: false }
+   */
+  nav?: VitePressNavOptions;
+  /**
+   * Whether to write docs JSON, or the output path to write it to.
+   *
+   * @default undefined
+   */
+  docsJson?: boolean | string;
+  /**
+   * Escape `<` and `>` in markdown heading lines to avoid HTML parsing in VitePress.
+   *
+   * @default false
+   */
+  escapeHeadingAngleBrackets?: boolean;
+}
+/** API docs options after defaults are applied and all paths are normalized. */
+interface ResolvedOxContentApiDocsOptions extends Omit<OxContentApiDocsOptions, 'root' | 'tsconfig' | 'entryPoints' | 'outDir' | 'extraction' | 'nav'> {
+  /** Absolute project root used as the base for all relative inputs. */
+  root: string;
+  /**
+   * Absolute TypeScript configuration path, when configured.
+   *
+   * @default undefined
+   */
+  tsconfig?: string;
+  /** Entry point specs with paths resolved to absolute filesystem paths. */
+  entryPoints: JsEntryPointSpec[];
+  /** Absolute output directory for generated markdown and optional artifacts. */
+  outDir: string;
+  /** Extraction options with defaults applied and external package paths resolved. */
+  extraction: ResolvedOxContentExtractionOptions;
+  /** VitePress navigation options with default integration settings applied. */
+  nav: Required<Pick<VitePressNavOptions, 'enabled' | 'insert' | 'virtualModule'>> & Omit<VitePressNavOptions, 'enabled' | 'insert' | 'virtualModule'>;
+}
+/** Navigation item generated from API docs metadata. */
+interface ApiDocsNavItem {
+  /** Human-readable title shown in generated navigation and sidebar items. */
+  title: string;
+  /** VitePress link path for the generated API docs page. */
+  path: string;
+  /** Nested navigation items for grouped modules or declaration hierarchies. */
+  children?: ApiDocsNavItem[];
+}
+/** Minimal VitePress sidebar item shape used by generated API docs. */
+interface VitePressSidebarItem {
+  /** Text label displayed in the VitePress sidebar. */
+  text?: string;
+  /** VitePress route path opened when the sidebar item is selected. */
+  link?: string;
+  /** Whether this item's nested children start collapsed. */
+  collapsed?: boolean;
+  /** Nested sidebar items displayed below this item. */
+  items?: VitePressSidebarItem[];
+}
+/** Options for merging generated sidebar items into an existing VitePress sidebar. */
+interface MergeVitePressSidebarOptions {
+  /** Positioning strategy used when inserting generated items into the sidebar. */
+  insert?: VitePressSidebarInsert;
+  /** Existing sidebar item text to replace when `insert` is set to `replace`. */
+  replaceText?: string;
+  /** Route key to update when the existing VitePress sidebar is a route map. */
+  sidebarRoute?: string;
+}
+/** Result produced by API docs generation. */
+interface OxContentApiDocsResult {
+  /** Generated markdown and artifact contents keyed by relative output path. */
+  files: Record<string, string>;
+  /** Navigation metadata derived from generated docs. */
+  nav: ApiDocsNavItem[];
+  /** Markdown module data generated from extracted declarations. */
+  docs: JsDocsMarkdownModule[];
+  /** Absolute paths for files written to disk or planned when `write` is `false`. */
+  generatedFiles: string[];
+  /** Diagnostic messages reported while extracting docs. */
+  diagnostics: string[];
+  /** Hash representing the current generation options and watched input files. */
+  hash: string;
+  /** Normalized options used for this generation run. */
+  resolvedOptions: ResolvedOxContentApiDocsOptions;
+}
+//#endregion
+//#region src/generate.d.ts
+/**
+ * Generates API reference markdown, navigation metadata, and optional artifacts.
+ *
+ * @example
+ * ```ts
+ * import { generateOxContentApiDocs } from 'vitepress-api-references'
+ *
+ * const result = await generateOxContentApiDocs({
+ *   entryPoints: ['src/index.ts'],
+ *   outDir: 'docs/api',
+ *   basePath: '/api'
+ * })
+ *
+ * console.log(result.generatedFiles)
+ * ```
+ *
+ * @param options - API docs generation options.
+ * @returns Generated API docs files, metadata, diagnostics, and resolved options.
+ */
+declare function generateOxContentApiDocs(options: OxContentApiDocsOptions): Promise<OxContentApiDocsResult>;
+//#endregion
+//#region src/vitepress.d.ts
+declare module 'vitepress' {
+  interface UserConfig {
+    apiDocs?: OxContentApiDocsOptions | false;
+  }
+}
 /**
- * vitepress api references entry point
+ * Adds generated API docs pages, sidebar data, and watch support to a VitePress config.
+ *
+ * @example
+ * ```ts
+ * import { defineConfig } from 'vitepress'
+ * import { withOxContentApiDocs } from 'vitepress-api-references'
+ *
+ * export default await withOxContentApiDocs(
+ *   defineConfig({
+ *     title: 'My Library',
+ *     apiDocs: {
+ *       entryPoints: ['src/index.ts'],
+ *       outDir: 'api',
+ *       basePath: '/api'
+ *     }
+ *   })
+ * )
+ * ```
  *
- * @module default
+ * @param config - VitePress user configuration.
+ * @param override - Optional API docs options applied over the configured options.
+ * @returns Updated VitePress user configuration.
  */
-declare function fn(): string;
+declare function withOxContentApiDocs(config: UserConfig, override?: OxContentApiDocsOptions): Promise<UserConfig>;
+//#endregion
+//#region src/sidebar.d.ts
+/**
+ * Converts API docs navigation metadata into VitePress sidebar items.
+ *
+ * @example
+ * ```ts
+ * import { toVitePressSidebarItems } from 'vitepress-api-references'
+ *
+ * const sidebarItems = toVitePressSidebarItems([
+ *   {
+ *     title: 'API',
+ *     path: '/api/',
+ *     children: [{ title: 'withOxContentApiDocs', path: '/api/with-ox-content-api-docs' }]
+ *   }
+ * ])
+ * ```
+ *
+ * @param nav - API docs navigation metadata.
+ * @param options - VitePress navigation options.
+ * @returns Generated VitePress sidebar items.
+ */
+declare function toVitePressSidebarItems(nav: ApiDocsNavItem[], options?: VitePressNavOptions): VitePressSidebarItem[];
+/**
+ * Creates a VitePress sidebar section from generated API docs navigation.
+ *
+ * @example
+ * ```ts
+ * import { createVitePressSidebarSection } from 'vitepress-api-references'
+ *
+ * const apiSection = createVitePressSidebarSection(apiDocsNav, {
+ *   section: {
+ *     text: 'API Reference',
+ *     collapsed: false
+ *   }
+ * })
+ * ```
+ *
+ * @param nav - API docs navigation metadata.
+ * @param options - VitePress navigation options.
+ * @returns Generated VitePress sidebar section.
+ */
+declare function createVitePressSidebarSection(nav: ApiDocsNavItem[], options?: VitePressNavOptions): VitePressSidebarItem;
+/**
+ * Merges generated API docs sidebar data into an existing VitePress sidebar.
+ *
+ * @example
+ * ```ts
+ * import { mergeVitePressSidebar } from 'vitepress-api-references'
+ *
+ * const sidebar = mergeVitePressSidebar(
+ *   [{ text: 'Guide', link: '/guide/' }],
+ *   { text: 'API Reference', items: [{ text: 'Config', link: '/api/config' }] },
+ *   { insert: 'append' }
+ * )
+ * ```
+ *
+ * @param sidebar - Existing VitePress sidebar configuration.
+ * @param generated - Generated API docs sidebar section.
+ * @param options - Sidebar merge options.
+ * @returns Updated VitePress sidebar configuration.
+ */
+declare function mergeVitePressSidebar(sidebar: unknown, generated: VitePressSidebarItem, options?: MergeVitePressSidebarOptions): unknown;
+//#endregion
+//#region src/index.d.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+
 //#endregion
-export { fn };
+export { type ApiDocsNavItem, type MergeVitePressSidebarOptions, type OxContentApiDocsOptions, type OxContentApiDocsResult, type OxContentExtractionOptions, type OxContentMarkdownOptions, type ResolvedOxContentApiDocsOptions, type VitePressNavOptions, type VitePressSidebarItem, createVitePressSidebarSection, generateOxContentApiDocs, mergeVitePressSidebar, toVitePressSidebarItems, withOxContentApiDocs };

package/dist/index.mjs

@@ -1,18 +1,528 @@
-import { createDebug } from "obug";
-//#region src/index.ts
+import path from "node:path";
+import { extractDocsFromEntryPoints, generateDocsDataJson, generateDocsMarkdown, generateDocsNavCode, generateDocsNavMetadataFromDocs } from "@ox-content/napi";
+import fs from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+//#region src/files.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Writes generated content only when the target file content changes.
+*
+* @param filePath - Output file path.
+* @param content - File content to write.
+* @returns Whether the file was written.
+*/
+async function writeGeneratedFile(filePath, content) {
+	await fs.mkdir(path.dirname(filePath), { recursive: true });
+	try {
+		if (await fs.readFile(filePath, "utf8") === content) return false;
+	} catch (error) {
+		if (!isNotFoundError(error)) throw error;
+	}
+	await fs.writeFile(filePath, content);
+	return true;
+}
+/**
+* Writes multiple generated files into an output directory.
+*
+* @param files - Generated file contents keyed by relative path.
+* @param outDir - Output directory used to resolve relative paths.
+* @returns Absolute paths for generated files.
+*/
+async function writeGeneratedFiles(files, outDir) {
+	const generatedFiles = [];
+	for (const [relativePath, content] of Object.entries(files)) {
+		const filePath = path.resolve(outDir, relativePath);
+		await writeGeneratedFile(filePath, content);
+		generatedFiles.push(filePath);
+	}
+	return generatedFiles;
+}
+function isNotFoundError(error) {
+	return typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT";
+}
+//#endregion
+//#region src/hash.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Creates a stable hash for API docs generation inputs.
+*
+* @param options - Resolved API docs options.
+* @returns Hash string for the current generation inputs.
+*/
+async function createGenerationHash(options) {
+	const hash = createHash("sha256");
+	hash.update(JSON.stringify(toHashableOptions(options)));
+	for (const filePath of collectInputFiles(options)) {
+		hash.update(filePath);
+		hash.update(await statHash(filePath));
+	}
+	return hash.digest("hex");
+}
+function toHashableOptions(options) {
+	return {
+		root: options.root,
+		tsconfig: options.tsconfig,
+		entryPoints: options.entryPoints,
+		outDir: options.outDir,
+		basePath: options.basePath,
+		githubUrl: options.githubUrl,
+		extraction: options.extraction,
+		markdown: options.markdown,
+		docsJson: options.docsJson,
+		escapeHeadingAngleBrackets: options.escapeHeadingAngleBrackets
+	};
+}
+function collectInputFiles(options) {
+	return [
+		...options.entryPoints.map((entry) => entry.path),
+		...options.tsconfig ? [options.tsconfig] : [],
+		...options.extraction.externalPackageSources?.map((source) => source.entry) ?? []
+	];
+}
+async function statHash(filePath) {
+	try {
+		const stat = await fs.stat(filePath);
+		return `${stat.mtimeMs}:${stat.size}`;
+	} catch {
+		return "missing";
+	}
+}
+//#endregion
+//#region src/options.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Resolves user API docs options into absolute paths and default values.
+*
+* @param options - User-facing API docs options.
+* @returns Resolved API docs options.
+*/
+function resolveApiDocsOptions(options) {
+	const root = toAbsolutePath(options.root ?? process.cwd(), process.cwd());
+	const outDir = toAbsolutePath(options.outDir, root);
+	const tsconfig = options.tsconfig ? toAbsolutePath(options.tsconfig, root) : void 0;
+	const extraction = options.extraction ?? {};
+	return {
+		...options,
+		root,
+		tsconfig,
+		outDir,
+		basePath: normalizeBasePath(options.basePath),
+		entryPoints: options.entryPoints.map((entry) => {
+			if (typeof entry === "string") return { path: toAbsolutePath(entry, root) };
+			return {
+				path: toAbsolutePath(entry.path, root),
+				name: entry.name
+			};
+		}),
+		extraction: {
+			private: extraction.private ?? false,
+			internal: extraction.internal ?? false,
+			externalDocs: extraction.externalDocs ?? false,
+			typeParameters: extraction.typeParameters ?? false,
+			externalPackageSources: extraction.externalPackageSources?.map((source) => ({
+				package: source.package,
+				entry: toAbsolutePath(source.entry, root)
+			}))
+		},
+		markdown: options.markdown ?? {},
+		nav: {
+			enabled: options.nav?.enabled ?? true,
+			insert: options.nav?.insert ?? "append",
+			virtualModule: options.nav?.virtualModule ?? false,
+			...options.nav
+		},
+		write: options.write ?? true,
+		escapeHeadingAngleBrackets: options.escapeHeadingAngleBrackets ?? false
+	};
+}
+/**
+* Merges base API docs options with override options.
+*
+* @param base - Base options from VitePress configuration.
+* @param override - Override options applied on top of the base options.
+* @returns Merged API docs options.
+*/
+function mergeApiDocsOptions(base, override) {
+	if (!override) return base;
+	const section = override.nav?.section ?? base.nav?.section;
+	const nav = {
+		...base.nav,
+		...override.nav
+	};
+	return {
+		...base,
+		...override,
+		extraction: {
+			...base.extraction,
+			...override.extraction
+		},
+		markdown: {
+			...base.markdown,
+			...override.markdown
+		},
+		nav: section ? {
+			...nav,
+			section
+		} : nav
+	};
+}
+function normalizeBasePath(basePath) {
+	const normalized = basePath.startsWith("/") ? basePath : `/${basePath}`;
+	return normalized.length > 1 ? normalized.replace(/\/+$/, "") : normalized;
+}
+function toAbsolutePath(value, baseDir) {
+	if (value instanceof URL) return fileURLToPath(value);
+	return path.isAbsolute(value) ? value : path.resolve(baseDir, value);
+}
+//#endregion
+//#region src/generate.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Generates API reference markdown, navigation metadata, and optional artifacts.
+*
+* @example
+* ```ts
+* import { generateOxContentApiDocs } from 'vitepress-api-references'
+*
+* const result = await generateOxContentApiDocs({
+*   entryPoints: ['src/index.ts'],
+*   outDir: 'docs/api',
+*   basePath: '/api'
+* })
+*
+* console.log(result.generatedFiles)
+* ```
+*
+* @param options - API docs generation options.
+* @returns Generated API docs files, metadata, diagnostics, and resolved options.
+*/
+async function generateOxContentApiDocs(options) {
+	const resolvedOptions = resolveApiDocsOptions(options);
+	const extractedDocs = extractDocsFromEntryPoints(resolvedOptions.entryPoints, {
+		root: resolvedOptions.root,
+		tsconfig: resolvedOptions.tsconfig,
+		...resolvedOptions.extraction
+	});
+	const docs = extractedDocs.map((module) => ({
+		file: module.name,
+		description: module.description,
+		sourcePath: module.sourcePath,
+		examples: module.examples,
+		tags: module.tags,
+		entries: module.entries.map((entry) => ({
+			...entry,
+			tags: entry.tags ? Object.entries(entry.tags).map(([tag, value]) => ({
+				tag,
+				value
+			})) : void 0,
+			hasBody: entry.hasBody ?? false
+		}))
+	}));
+	const rawFiles = generateDocsMarkdown(docs, {
+		...resolvedOptions.markdown,
+		basePath: resolvedOptions.basePath,
+		githubUrl: resolvedOptions.githubUrl
+	});
+	const files = resolvedOptions.escapeHeadingAngleBrackets ? escapeHeadingAngleBrackets(rawFiles) : rawFiles;
+	const nav = generateDocsNavMetadataFromDocs(docs, {
+		basePath: resolvedOptions.basePath,
+		pathStrategy: resolvedOptions.markdown?.pathStrategy,
+		groupOrder: resolvedOptions.markdown?.groupOrder,
+		sort: resolvedOptions.markdown?.sort,
+		sortEntryPoints: resolvedOptions.markdown?.sortEntryPoints,
+		kindSortOrder: resolvedOptions.markdown?.kindSortOrder
+	});
+	const generatedFiles = resolvedOptions.write ? await writeGeneratedFiles(files, resolvedOptions.outDir) : Object.keys(files).map((file) => path.resolve(resolvedOptions.outDir, file));
+	if (resolvedOptions.write) await writeOptionalArtifacts(resolvedOptions, docs, nav, generatedFiles);
+	return {
+		files,
+		nav,
+		docs,
+		generatedFiles,
+		diagnostics: extractedDocs.flatMap((module) => module.diagnostics.map((diagnostic) => diagnostic.message)),
+		hash: await createGenerationHash(resolvedOptions),
+		resolvedOptions
+	};
+}
+async function writeOptionalArtifacts(options, docs, nav, generatedFiles) {
+	if (options.docsJson) {
+		const docsJsonPath = typeof options.docsJson === "string" ? options.docsJson : "docs.json";
+		const outputPath = path.isAbsolute(docsJsonPath) ? docsJsonPath : path.join(options.outDir, docsJsonPath);
+		await writeGeneratedFile(outputPath, `${generateDocsDataJson(docs, (/* @__PURE__ */ new Date()).toISOString())}\n`);
+		generatedFiles.push(outputPath);
+	}
+	if (options.nav.outputFile) {
+		const outputPath = path.isAbsolute(options.nav.outputFile) ? options.nav.outputFile : path.join(options.outDir, options.nav.outputFile);
+		await writeGeneratedFile(outputPath, generateDocsNavCode(nav, options.nav.exportName ?? "apiDocsNav"));
+		generatedFiles.push(outputPath);
+	}
+}
+function escapeHeadingAngleBrackets(files) {
+	return Object.fromEntries(Object.entries(files).map(([filePath, content]) => [filePath, content.split("\n").map((line) => /^#{1,6}\s/.test(line) ? line.replaceAll("<", "&lt;").replaceAll(">", "&gt;") : line).join("\n")]));
+}
+//#endregion
+//#region src/sidebar.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Converts API docs navigation metadata into VitePress sidebar items.
+*
+* @example
+* ```ts
+* import { toVitePressSidebarItems } from 'vitepress-api-references'
+*
+* const sidebarItems = toVitePressSidebarItems([
+*   {
+*     title: 'API',
+*     path: '/api/',
+*     children: [{ title: 'withOxContentApiDocs', path: '/api/with-ox-content-api-docs' }]
+*   }
+* ])
+* ```
+*
+* @param nav - API docs navigation metadata.
+* @param options - VitePress navigation options.
+* @returns Generated VitePress sidebar items.
+*/
+function toVitePressSidebarItems(nav, options = {}) {
+	return nav.map((item) => toSidebarItem(item, options, 0));
+}
 /**
-* vitepress api references entry point
+* Creates a VitePress sidebar section from generated API docs navigation.
+*
+* @example
+* ```ts
+* import { createVitePressSidebarSection } from 'vitepress-api-references'
+*
+* const apiSection = createVitePressSidebarSection(apiDocsNav, {
+*   section: {
+*     text: 'API Reference',
+*     collapsed: false
+*   }
+* })
+* ```
 *
-* @module default
+* @param nav - API docs navigation metadata.
+* @param options - VitePress navigation options.
+* @returns Generated VitePress sidebar section.
 */
+function createVitePressSidebarSection(nav, options = {}) {
+	const items = toVitePressSidebarItems(nav, options);
+	const section = options.section;
+	if (!section) return { items };
+	return {
+		text: section.text,
+		collapsed: section.collapsed,
+		items
+	};
+}
+/**
+* Merges generated API docs sidebar data into an existing VitePress sidebar.
+*
+* @example
+* ```ts
+* import { mergeVitePressSidebar } from 'vitepress-api-references'
+*
+* const sidebar = mergeVitePressSidebar(
+*   [{ text: 'Guide', link: '/guide/' }],
+*   { text: 'API Reference', items: [{ text: 'Config', link: '/api/config' }] },
+*   { insert: 'append' }
+* )
+* ```
+*
+* @param sidebar - Existing VitePress sidebar configuration.
+* @param generated - Generated API docs sidebar section.
+* @param options - Sidebar merge options.
+* @returns Updated VitePress sidebar configuration.
+*/
+function mergeVitePressSidebar(sidebar, generated, options = {}) {
+	const insert = options.insert ?? "append";
+	if (typeof insert === "function") return insert(sidebar, generated);
+	if (isSidebarMulti(sidebar)) {
+		const route = options.sidebarRoute;
+		if (!route) return sidebar;
+		return {
+			...sidebar,
+			[route]: mergeVitePressSidebar(sidebar[route], generated, options)
+		};
+	}
+	const items = Array.isArray(sidebar) ? sidebar : [];
+	if (insert === "prepend") return [generated, ...items];
+	if (insert === "replace") return replaceSidebarItem(items, generated, options.replaceText);
+	return [...items, generated];
+}
+function toSidebarItem(item, options, depth) {
+	const children = item.children?.map((child) => toSidebarItem(child, options, depth + 1));
+	const sidebarItem = { text: item.title };
+	const collapsed = resolveCollapsed(item, options, depth);
+	if (collapsed !== void 0) sidebarItem.collapsed = collapsed;
+	if (children?.length) {
+		sidebarItem.items = children;
+		if (depth === 0 && item.path) sidebarItem.link = item.path;
+	} else if (item.path) sidebarItem.link = item.path;
+	return sidebarItem;
+}
+function replaceSidebarItem(items, generated, replaceText) {
+	let replaced = false;
+	const next = items.map((item) => {
+		if (isSidebarItem(item)) {
+			if (replaceText && item.text === replaceText) {
+				replaced = true;
+				return generated;
+			}
+			if (replaceText && item.items) {
+				const nested = replaceSidebarItem(item.items, generated, replaceText);
+				if (nested !== item.items) {
+					replaced = true;
+					return {
+						...item,
+						items: nested
+					};
+				}
+			}
+		}
+		return item;
+	});
+	return replaced ? next : [...items, generated];
+}
+function resolveCollapsed(item, options, depth) {
+	if (typeof options.collapsed === "function") return options.collapsed(item, depth);
+	return options.collapsed;
+}
+function isSidebarItem(value) {
+	return typeof value === "object" && value !== null;
+}
+function isSidebarMulti(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value) && Object.values(value).every((item) => Array.isArray(item));
+}
+//#endregion
+//#region src/watch.ts
 /**
 * @author kazuya kawaguchi (a.k.a. kazupon)
 * @license MIT
 */
-const debug = createDebug("vitepress-api-references");
-function fn() {
-	debug("fn called");
-	return "Hello, tsdown!";
+/**
+* Creates a Vite plugin that regenerates API docs during development.
+*
+* @param options - API docs generation options.
+* @param pluginOptions - Initial plugin state options.
+* @returns Vite plugin for API docs generation and reloads.
+*/
+function createApiDocsVitePlugin(options, pluginOptions = {}) {
+	const resolvedOptions = resolveApiDocsOptions(options);
+	let lastHash = pluginOptions.initialHash;
+	let navItems = pluginOptions.initialNav ?? [];
+	let debounceTimer;
+	async function regenerate(force = false) {
+		const nextHash = await createGenerationHash(resolvedOptions);
+		if (!force && lastHash === nextHash) return;
+		const result = await generateOxContentApiDocs(options);
+		lastHash = result.hash;
+		navItems = result.nav;
+	}
+	return {
+		name: "vitepress-api-references:api-docs",
+		enforce: "post",
+		async buildStart() {
+			await regenerate();
+		},
+		configureServer(server) {
+			const watchedFiles = getWatchedFiles(options);
+			server.watcher.add(watchedFiles);
+			server.watcher.on("all", (_event, filePath) => {
+				if (!watchedFiles.includes(filePath)) return;
+				queueRegenerate(server, () => regenerate(true));
+			});
+		},
+		resolveId(id) {
+			if (resolvedOptions.nav.virtualModule && id === resolvedOptions.nav.virtualModule) return id;
+		},
+		load(id) {
+			if (resolvedOptions.nav.virtualModule && id === resolvedOptions.nav.virtualModule) return `export const navItems = ${JSON.stringify(navItems)}\n`;
+		}
+	};
+	function queueRegenerate(server, run) {
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(() => {
+			run().then(() => {
+				server.ws.send({ type: "full-reload" });
+			}).catch((error) => {
+				console.error(error);
+			});
+		}, 100);
+	}
 }
+function getWatchedFiles(options) {
+	const resolvedOptions = resolveApiDocsOptions(options);
+	return [...resolvedOptions.entryPoints.map((entry) => entry.path), ...resolvedOptions.extraction.externalPackageSources?.map((source) => source.entry) ?? []];
+}
+//#endregion
+//#region src/vitepress.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
+/**
+* Adds generated API docs pages, sidebar data, and watch support to a VitePress config.
+*
+* @example
+* ```ts
+* import { defineConfig } from 'vitepress'
+* import { withOxContentApiDocs } from 'vitepress-api-references'
+*
+* export default await withOxContentApiDocs(
+*   defineConfig({
+*     title: 'My Library',
+*     apiDocs: {
+*       entryPoints: ['src/index.ts'],
+*       outDir: 'api',
+*       basePath: '/api'
+*     }
+*   })
+* )
+* ```
+*
+* @param config - VitePress user configuration.
+* @param override - Optional API docs options applied over the configured options.
+* @returns Updated VitePress user configuration.
+*/
+async function withOxContentApiDocs(config, override) {
+	const configuredOptions = config.apiDocs;
+	if (configuredOptions === false && !override) return config;
+	const baseOptions = configuredOptions === false ? void 0 : configuredOptions;
+	const apiDocsOptions = override ? baseOptions ? mergeApiDocsOptions(baseOptions, override) : override : baseOptions;
+	if (!apiDocsOptions) return config;
+	const result = await generateOxContentApiDocs(apiDocsOptions);
+	const sidebarSection = createVitePressSidebarSection(result.nav, result.resolvedOptions.nav);
+	config.themeConfig ??= {};
+	config.themeConfig.sidebar = mergeVitePressSidebar(config.themeConfig.sidebar, sidebarSection, result.resolvedOptions.nav);
+	config.vite ??= {};
+	config.vite.plugins = [...Array.isArray(config.vite.plugins) ? config.vite.plugins : [], createApiDocsVitePlugin(apiDocsOptions, {
+		initialHash: result.hash,
+		initialNav: result.nav
+	})];
+	return config;
+}
+//#endregion
+//#region src/index.ts
+/**
+* @author kazuya kawaguchi (a.k.a. kazupon)
+* @license MIT
+*/
 //#endregion
-export { fn };
+export { createVitePressSidebarSection, generateOxContentApiDocs, mergeVitePressSidebar, toVitePressSidebarItems, withOxContentApiDocs };

package/package.json

@@ -1,7 +1,14 @@
 {
   "name": "vitepress-api-references",
-  "version": "0.0.0",
-  "description": "Enable JSDoc API Reference",
+  "version": "0.1.0",
+  "description": "Enable JSDoc API Reference for VitePress",
+  "keywords": [
+    "api-references",
+    "docs",
+    "documentation",
+    "markdown",
+    "vitepress"
+  ],
   "homepage": "https://github.com/kazupon/vitepress-api-references#readme",
   "bugs": {
     "url": "https://github.com/kazupon/vitepress-api-references/issues"
@@ -38,7 +45,11 @@
     "build": "vp pack",
     "knip": "knip",
     "dev": "vp pack --watch",
+    "docs:build": "vp pack && vp exec vitepress build docs",
+    "docs:dev": "vp pack && vp exec vitepress dev docs",
+    "docs:standalone": "vp pack && node standalone/generate.ts",
     "test": "vp test",
+    "test:fixtures": "vp exec vitepress build tests/fixtures/basic/docs",
     "check": "vp check && knip",
     "prepublishOnly": "vp run build",
     "release": "bumpp --commit \"release: v%s\" --all --push --tag",
@@ -46,18 +57,25 @@
     "prepare": "vp config"
   },
   "dependencies": {
-    "obug": "^2.1.2"
+    "@ox-content/napi": "^2.63.0"
   },
   "devDependencies": {
-    "@kazupon/eslint-plugin": "^0.7.1",
-    "@kazupon/vp-config": "^0.2.0",
+    "@kazupon/vp-config": "^0.3.2",
     "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260509.2",
+    "@typescript/native-preview": "7.0.0-dev.20260527.2",
     "bumpp": "^11.1.0",
     "gh-changelogen": "^0.2.8",
     "knip": "^6.16.0",
+    "oxc-minify": "^0.134.0",
+    "pkg-pr-new": "^0.0.75",
     "typescript": "^6.0.3",
-    "vite-plus": "catalog:"
+    "vite": "catalog:",
+    "vite-plus": "catalog:",
+    "vitepress": "2.0.0-alpha.17"
+  },
+  "peerDependencies": {
+    "vite": ">=5",
+    "vitepress": ">=2.0.0-alpha.17"
   },
   "engines": {
     "node": ">= 22"