docs: upgrade typedoc

diff --git a/packages/docs/.gitignore b/packages/docs/.gitignore
index 4f2fc4ac0efe8c9ff93bdbf779ccc913f1725964..45f548031c832b29b58897899b88e029e4ed395e 100644 (file)
--- a/packages/docs/.gitignore
+++ b/packages/docs/.gitignore
@@ -1 +1,2 @@
 .vitepress/cache
+api

diff --git a/packages/docs/.vitepress/config/en.ts b/packages/docs/.vitepress/config/en.ts
index b4e7f0e4b48e521d6684d11a67713b1f48bf5c57..e93f5169701af0b0621c0c64a91eea0eb1ef2987 100644 (file)
--- a/packages/docs/.vitepress/config/en.ts
+++ b/packages/docs/.vitepress/config/en.ts
@@ -1,4 +1,5 @@
 import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+import typedocSidebar from '../../api/typedoc-sidebar.json'
 
 export const META_URL = 'https://router.vuejs.org'
 export const META_TITLE = 'Vue Router'
@@ -53,6 +54,12 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
     ],
 
     sidebar: {
+      '/api/': [
+        {
+          text: 'API',
+          items: typedocSidebar,
+        },
+      ],
       // catch-all fallback
       '/': [
         {
@@ -179,13 +186,6 @@ export const enConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           ],
         },
       ],
-
-      '/api/': [
-        {
-          text: 'packages',
-          items: [{ text: 'vue-router', link: '/api/' }],
-        },
-      ],
     },
   },
 }

diff --git a/packages/docs/.vitepress/config/zh.ts b/packages/docs/.vitepress/config/zh.ts
index dbc6ba4abfbdb8a0c14e7b5a4e6cc0713c915f81..312f9784ed260bc859f129a434d197ede3d79bf6 100644 (file)
--- a/packages/docs/.vitepress/config/zh.ts
+++ b/packages/docs/.vitepress/config/zh.ts
@@ -1,4 +1,6 @@
 import type { DefaultTheme, LocaleSpecificConfig } from 'vitepress'
+import typedocSidebar from '../../api/typedoc-sidebar.json'
+// TODO: rework the typedoc sidebar to include the /zh/ prefix
 
 export const META_URL = 'https://router.vuejs.org'
 export const META_TITLE = 'Vue Router'
@@ -57,6 +59,12 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
     ],
 
     sidebar: {
+      '/zh/api/': [
+        {
+          text: 'API',
+          items: typedocSidebar,
+        },
+      ],
       '/zh/': [
         {
           text: '设置',
@@ -186,13 +194,6 @@ export const zhConfig: LocaleSpecificConfig<DefaultTheme.Config> = {
           ],
         },
       ],
-
-      '/zh/api/': [
-        {
-          text: 'packages',
-          items: [{ text: 'vue-router', link: '/zh/api/' }],
-        },
-      ],
     },
   },
 }

diff --git a/packages/docs/package.json b/packages/docs/package.json
index 4765889c24ecd305a04b7a9f40d61b40d1f8a74f..05815c5636a8566b5358817257425d6c9ed0a852 100644 (file)
--- a/packages/docs/package.json
+++ b/packages/docs/package.json
@@ -14,8 +14,9 @@
   },
   "dependencies": {
     "simple-git": "^3.28.0",
+    "typedoc-vitepress-theme": "^1.1.2",
     "vitepress": "1.6.3",
-    "vitepress-translation-helper": "^0.2.1",
+    "vitepress-translation-helper": "^0.2.2",
     "vue-router": "workspace:*"
   }
 }

diff --git a/packages/docs/run-typedoc.mjs b/packages/docs/run-typedoc.mjs
index 790b14b9a6affdd34863cea4879af4410b3317d0..60c398e37b7fd7bee09e53496541b932f0154e08 100644 (file)
--- a/packages/docs/run-typedoc.mjs
+++ b/packages/docs/run-typedoc.mjs
@@ -1,15 +1,21 @@
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
 import { createTypeDocApp } from './typedoc-markdown.mjs'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
 
 createTypeDocApp({
-  name: 'API Documentation',
+  textContentMappings: {
+    'title.indexPage': 'API Reference',
+    'title.memberPage': '{name}',
+  },
   tsconfig: path.resolve(__dirname, './typedoc.tsconfig.json'),
+  // entryPointStrategy: 'packages',
   categorizeByGroup: true,
   githubPages: false,
-  disableSources: true, // some links are in node_modules and it's ugly
-  plugin: ['typedoc-plugin-markdown'],
+  readme: 'none',
+  indexFormat: 'table',
+  disableSources: true,
+  plugin: ['typedoc-plugin-markdown', 'typedoc-vitepress-theme'],
+  useCodeBlocks: true,
   entryPoints: [path.resolve(__dirname, '../router/src/index.ts')],
 }).then(app => app.build())

diff --git a/packages/docs/typedoc-markdown.mjs b/packages/docs/typedoc-markdown.mjs
index 3c84b4e3302d04f1e422db52d709d63933a170e4..dcae3a8a2dc94ac1a45ed3154b721f41edcce557 100644 (file)
--- a/packages/docs/typedoc-markdown.mjs
+++ b/packages/docs/typedoc-markdown.mjs
@@ -1,13 +1,12 @@
 // @ts-check
 import fs from 'node:fs/promises'
 import path from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { Application, PageEvent, TSConfigReader } from 'typedoc'
+import { Application, TSConfigReader, PageEvent } from 'typedoc'
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const __dirname = path.dirname(new URL(import.meta.url).pathname)
 
+/** @satisfies {Partial<import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions>} */
 const DEFAULT_OPTIONS = {
-  // disableOutputCheck: true,
   cleanOutputDir: true,
   excludeInternal: false,
   readme: 'none',
@@ -72,7 +71,7 @@ export async function createTypeDocApp(config = {}) {
     if (project) {
       // Rendered docs
       try {
-        await app.generateDocs(project, options.out)
+        await app.generateOutputs(project)
         app.logger.info(`generated at ${options.out}.`)
       } catch (error) {
         app.logger.error(error)
@@ -88,6 +87,12 @@ export async function createTypeDocApp(config = {}) {
   }
 }
 
+/**
+ * checks if a path exists
+ *
+ * @async
+ * @param {string} path
+ */
 async function exists(path) {
   try {
     await fs.access(path)
@@ -108,7 +113,7 @@ async function exists(path) {
  */
 function prependYAML(contents, vars) {
   return contents
-    .replace(/^/, `${toYAML(vars)}\n\n`)
+    .replace(/^/, toYAML(vars) + '\n\n')
     .replace(/[\r\n]{3,}/g, '\n\n')
 }
 

diff --git a/packages/docs/typedoc.tsconfig.json b/packages/docs/typedoc.tsconfig.json
index 3ca328f8364f54107826ca88cb94450d615ed0bc..4601fbf47ea36281f105614191b37d8467c64bcb 100644 (file)
--- a/packages/docs/typedoc.tsconfig.json
+++ b/packages/docs/typedoc.tsconfig.json
@@ -31,6 +31,6 @@
     "removeComments": false,
     "jsx": "preserve",
     "lib": ["esnext", "dom"],
-    "types": ["node"]
+    "types": ["vitest", "node", "vite/client"]
   }
 }

diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ca41b93a51d191d56b1dca4107fa6c39f953c390..828d69a789a857b9293405ac99c7bd7848e18fed 100644 (file)
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -65,12 +65,15 @@ importers:
       simple-git:
         specifier: ^3.28.0
         version: 3.28.0
+      typedoc-vitepress-theme:
+        specifier: ^1.1.2
+        version: 1.1.2(typedoc-plugin-markdown@4.7.0(typedoc@0.28.7(typescript@5.8.3)))
       vitepress:
         specifier: 1.6.3
         version: 1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3)
       vitepress-translation-helper:
-        specifier: ^0.2.1
-        version: 0.2.1(vitepress@1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3))(vue@3.5.17(typescript@5.8.3))
+        specifier: ^0.2.2
+        version: 0.2.2(vitepress@1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3))(vue@3.5.17(typescript@5.8.3))
       vue-router:
         specifier: workspace:*
         version: link:../router
@@ -4211,6 +4214,11 @@ packages:
     peerDependencies:
       typedoc: 0.28.x
 
+  typedoc-vitepress-theme@1.1.2:
+    resolution: {integrity: sha512-hQvCZRr5uKDqY1bRuY1+eNTNn6d4TE4OP5pnw65Y7WGgajkJW9X1/lVJK2UJpcwCmwkdjw1QIO49H9JQlxWhhw==}
+    peerDependencies:
+      typedoc-plugin-markdown: '>=4.4.0'
+
   typedoc@0.28.7:
     resolution: {integrity: sha512-lpz0Oxl6aidFkmS90VQDQjk/Qf2iw0IUvFqirdONBdj7jPSN9mGXhy66BcGNDxx5ZMyKKiBVAREvPEzT6Uxipw==}
     engines: {node: '>= 18', pnpm: '>= 10'}
@@ -4342,8 +4350,8 @@ packages:
       terser:
         optional: true
 
-  vitepress-translation-helper@0.2.1:
-    resolution: {integrity: sha512-zYjakGIdVDonT1P85OkeQcdE6e8vdmKiVclHB7DGcTzFUwb2D0w+hcC31AGneB5wa5IiqEoipycSTYNKM0YKJg==}
+  vitepress-translation-helper@0.2.2:
+    resolution: {integrity: sha512-xqE4p1iUmsADKyA8W/02POtEwL0ZMcY2Ogj4Shuh70392UslB5JhrgCdF1j61NIQhgy/wgAGhn33QZdksN6IqQ==}
     hasBin: true
     peerDependencies:
       vitepress: ^1.0.0
@@ -8659,6 +8667,10 @@ snapshots:
     dependencies:
       typedoc: 0.28.7(typescript@5.8.3)
 
+  typedoc-vitepress-theme@1.1.2(typedoc-plugin-markdown@4.7.0(typedoc@0.28.7(typescript@5.8.3))):
+    dependencies:
+      typedoc-plugin-markdown: 4.7.0(typedoc@0.28.7(typescript@5.8.3))
+
   typedoc@0.28.7(typescript@5.8.3):
     dependencies:
       '@gerrit0/mini-shiki': 3.8.0
@@ -8790,7 +8802,7 @@ snapshots:
       fsevents: 2.3.3
       terser: 5.43.1
 
-  vitepress-translation-helper@0.2.1(vitepress@1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3))(vue@3.5.17(typescript@5.8.3)):
+  vitepress-translation-helper@0.2.2(vitepress@1.6.3(@algolia/client-search@5.34.0)(@types/node@24.0.14)(axios@1.10.0)(postcss@8.5.6)(search-insights@2.17.3)(terser@5.43.1)(typescript@5.8.3))(vue@3.5.17(typescript@5.8.3)):
     dependencies:
       minimist: 1.2.8
       simple-git: 3.28.0