vitepress-api-references 0.1.0 → 0.2.1

package/README.md

@@ -8,7 +8,7 @@ Enable JSDoc API Reference for VitePress.
 
 ### 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.
+This repository uses the VitePress integration to generate and serve its own API reference docs. The generated API reference site is published at <https://kazupon.github.io/vitepress-api-references/>. 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'
@@ -20,16 +20,18 @@ export default defineConfig(
       sidebar: [{ text: 'Guide', link: '/' }, { text: 'API References' }]
     },
     apiDocs: {
-      entryPoints: [{ path: 'src/index.ts', name: 'default' }],
+      entryPoints: [{ path: 'src/index.ts' }],
       outDir: 'docs/api',
       basePath: '/api',
       markdown: {
         pathStrategy: 'typedoc',
+        singleEntryRoot: 'flatten',
         renderStyle: 'markdown',
         indexFormat: 'table'
       },
       nav: {
-        section: { text: 'API References', collapsed: false },
+        section: { text: 'API References' },
+        collapsed: true,
         insert: 'replace',
         replaceText: 'API References'
       }
@@ -46,7 +48,7 @@ Use `generateOxContentApiDocs` when you want to generate markdown files directly
 import { generateOxContentApiDocs } from 'vitepress-api-references'
 
 const result = await generateOxContentApiDocs({
-  entryPoints: [{ path: 'src/index.ts', name: 'default' }],
+  entryPoints: [{ path: 'src/index.ts', name: 'main' }],
   outDir: 'standalone',
   basePath: '/standalone',
   markdown: {

package/dist/index.d.mts

@@ -21,6 +21,7 @@ interface VitePressSidebarSectionOptions {
   text: string;
   /**
    * Whether the generated top-level sidebar section starts collapsed in VitePress.
+   * When omitted, a boolean `nav.collapsed` value is used.
    *
    * @default undefined
    */
@@ -100,6 +101,7 @@ interface VitePressNavOptions {
   sidebarRoute?: string;
   /**
    * Collapsed state for generated sidebar branches, or a resolver called per item.
+   * A boolean value also controls the top-level section when `section.collapsed` is omitted.
    *
    * @default undefined
    */
@@ -294,13 +296,21 @@ declare module 'vitepress' {
  * import { defineConfig } from 'vitepress'
  * import { withOxContentApiDocs } from 'vitepress-api-references'
  *
- * export default await withOxContentApiDocs(
- *   defineConfig({
+ * export default defineConfig(
+ *   await withOxContentApiDocs({
  *     title: 'My Library',
+ *     themeConfig: {
+ *       sidebar: [{ text: 'Guide', link: '/' }, { text: 'API Reference' }]
+ *     },
  *     apiDocs: {
- *       entryPoints: ['src/index.ts'],
- *       outDir: 'api',
- *       basePath: '/api'
+ *       entryPoints: [{ path: 'src/index.ts', name: 'default' }],
+ *       outDir: 'docs/api',
+ *       basePath: '/api',
+ *       nav: {
+ *         section: { text: 'API Reference', collapsed: false },
+ *         insert: 'replace',
+ *         replaceText: 'API Reference'
+ *       }
  *     }
  *   })
  * )

package/dist/index.mjs

@@ -240,6 +240,7 @@ async function generateOxContentApiDocs(options) {
 	const nav = generateDocsNavMetadataFromDocs(docs, {
 		basePath: resolvedOptions.basePath,
 		pathStrategy: resolvedOptions.markdown?.pathStrategy,
+		singleEntryRoot: resolvedOptions.markdown?.singleEntryRoot,
 		groupOrder: resolvedOptions.markdown?.groupOrder,
 		sort: resolvedOptions.markdown?.sort,
 		sortEntryPoints: resolvedOptions.markdown?.sortEntryPoints,
@@ -327,7 +328,7 @@ function createVitePressSidebarSection(nav, options = {}) {
 	if (!section) return { items };
 	return {
 		text: section.text,
-		collapsed: section.collapsed,
+		collapsed: resolveSectionCollapsed(options),
 		items
 	};
 }
@@ -369,36 +370,44 @@ function mergeVitePressSidebar(sidebar, generated, options = {}) {
 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) {
+		const collapsed = resolveCollapsed(item, options, depth);
+		if (collapsed !== void 0) sidebarItem.collapsed = collapsed;
 		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) {
+	const result = replaceSidebarItemRecursive(items, generated, replaceText);
+	return result.replaced ? result.items : [...items, generated];
+}
+function replaceSidebarItemRecursive(items, generated, replaceText) {
 	let replaced = false;
-	const next = items.map((item) => {
-		if (isSidebarItem(item)) {
+	return {
+		items: items.map((item) => {
+			if (!isSidebarItem(item)) return 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) {
+			if (replaceText && Array.isArray(item.items)) {
+				const nested = replaceSidebarItemRecursive(item.items, generated, replaceText);
+				if (nested.replaced) {
 					replaced = true;
 					return {
 						...item,
-						items: nested
+						items: nested.items
 					};
 				}
 			}
-		}
-		return item;
-	});
-	return replaced ? next : [...items, generated];
+			return item;
+		}),
+		replaced
+	};
+}
+function resolveSectionCollapsed(options) {
+	return options.section?.collapsed ?? (typeof options.collapsed === "boolean" ? options.collapsed : void 0);
 }
 function resolveCollapsed(item, options, depth) {
 	if (typeof options.collapsed === "function") return options.collapsed(item, depth);
@@ -485,13 +494,21 @@ function getWatchedFiles(options) {
 * import { defineConfig } from 'vitepress'
 * import { withOxContentApiDocs } from 'vitepress-api-references'
 *
-* export default await withOxContentApiDocs(
-*   defineConfig({
+* export default defineConfig(
+*   await withOxContentApiDocs({
 *     title: 'My Library',
+*     themeConfig: {
+*       sidebar: [{ text: 'Guide', link: '/' }, { text: 'API Reference' }]
+*     },
 *     apiDocs: {
-*       entryPoints: ['src/index.ts'],
-*       outDir: 'api',
-*       basePath: '/api'
+*       entryPoints: [{ path: 'src/index.ts', name: 'default' }],
+*       outDir: 'docs/api',
+*       basePath: '/api',
+*       nav: {
+*         section: { text: 'API Reference', collapsed: false },
+*         insert: 'replace',
+*         replaceText: 'API Reference'
+*       }
 *     }
 *   })
 * )
@@ -508,7 +525,7 @@ async function withOxContentApiDocs(config, override) {
 	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);
+	const sidebarSection = removeMissingBranchLinks(createVitePressSidebarSection(result.nav, result.resolvedOptions.nav), createGeneratedRoutePathSet(result.files, result.resolvedOptions.basePath));
 	config.themeConfig ??= {};
 	config.themeConfig.sidebar = mergeVitePressSidebar(config.themeConfig.sidebar, sidebarSection, result.resolvedOptions.nav);
 	config.vite ??= {};
@@ -518,6 +535,28 @@ async function withOxContentApiDocs(config, override) {
 	})];
 	return config;
 }
+function createGeneratedRoutePathSet(files, basePath) {
+	const routes = /* @__PURE__ */ new Set();
+	for (const filePath of Object.keys(files)) {
+		if (!filePath.endsWith(".md")) continue;
+		const routePath = filePath.slice(0, -3);
+		if (routePath === "index") routes.add(normalizeRoutePath(basePath));
+		else if (routePath.endsWith("/index")) routes.add(normalizeRoutePath(`${basePath}/${routePath.slice(0, -6)}`));
+		else routes.add(normalizeRoutePath(`${basePath}/${routePath}`));
+	}
+	return routes;
+}
+function removeMissingBranchLinks(item, routes) {
+	const next = { ...item };
+	if (item.items) next.items = item.items.map((child) => removeMissingBranchLinks(child, routes));
+	if (next.items?.length && next.link && !routes.has(normalizeRoutePath(next.link))) delete next.link;
+	return next;
+}
+function normalizeRoutePath(routePath) {
+	const withoutMarkdown = routePath.endsWith(".md") ? routePath.slice(0, -3) : routePath;
+	const normalized = withoutMarkdown.startsWith("/") ? withoutMarkdown : `/${withoutMarkdown}`;
+	return normalized.length > 1 ? normalized.replace(/\/+$/, "") : normalized;
+}
 //#endregion
 //#region src/index.ts
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitepress-api-references",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Enable JSDoc API Reference for VitePress",
   "keywords": [
     "api-references",
@@ -45,9 +45,10 @@
     "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",
+    "docs:build": "vp exec vitepress build docs",
+    "docs:preview": "vp exec vitepress preview docs",
+    "docs:dev": "vp exec vitepress dev docs",
+    "docs:standalone": "node standalone/generate.ts",
     "test": "vp test",
     "test:fixtures": "vp exec vitepress build tests/fixtures/basic/docs",
     "check": "vp check && knip",
@@ -57,12 +58,12 @@
     "prepare": "vp config"
   },
   "dependencies": {
-    "@ox-content/napi": "^2.63.0"
+    "@ox-content/napi": "^2.66.0"
   },
   "devDependencies": {
     "@kazupon/vp-config": "^0.3.2",
     "@types/node": "^25.9.1",
-    "@typescript/native-preview": "7.0.0-dev.20260527.2",
+    "@typescript/native-preview": "7.0.0-dev.20260602.1",
     "bumpp": "^11.1.0",
     "gh-changelogen": "^0.2.8",
     "knip": "^6.16.0",