docs: typedoc for vitepress

Author: sxzz

.gitignore

@@ -10,4 +10,6 @@ temp
 
 docs/.vitepress/dist
 docs/.vitepress/cache
+
 docs/reference/api
+docs/zh-CN/reference/api

.vscode/settings.json

@@ -2,9 +2,7 @@
   "editor.formatOnSave": true,
   "cSpell.words": ["tsdown"],
   "files.readonlyInclude": {
-    "docs/**/config-options.md": true,
-    "docs/**/workspace.md": true,
-    "docs/**/type-aliases/*.md": true
+    "docs/**/reference/api/**": true
   },
   "typescript.tsdk": "node_modules/typescript/lib"
 }

docs/.vitepress/config/theme.ts

@@ -1,6 +1,27 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
 import { createTranslate } from '../i18n/utils'
 import type { DefaultTheme, HeadConfig, LocaleConfig } from 'vitepress'
 
+async function getTypedocSidebar() {
+  const filepath = path.resolve(
+    import.meta.dirname,
+    '../../reference/api/typedoc-sidebar.json',
+  )
+  if (!existsSync(filepath)) return []
+
+  try {
+    return JSON.parse(
+      await readFile(filepath, 'utf8'),
+    ) as DefaultTheme.SidebarItem[]
+  } catch {
+    return []
+  }
+}
+
+const typedocSidebar = await getTypedocSidebar()
+
 export function getLocaleConfig(lang: string) {
   const t = createTranslate(lang)
 
@@ -96,8 +117,18 @@ export function getLocaleConfig(lang: string) {
       text: t('API Reference'),
       base: `${urlPrefix}/reference`,
       items: [
-        { text: t('Config Options'), link: '/config-options.md' },
         { text: t('Command Line Interface'), link: '/cli.md' },
+        {
+          text: t('Config Options'),
+          link: '/api/Interface.Options.md',
+        },
+        {
+          text: t('Type Definitions'),
+          items: typedocSidebar
+            .flatMap((i) => i.items!)
+            .filter((i) => i.text !== 'Options'),
+          collapsed: true,
+        },
       ],
     },
   ]

docs/.vitepress/i18n/translate-map.ts

@@ -39,8 +39,9 @@ export const zhCN = {
   Benchmark: '性能基准',
   FAQ: '常见问题',
 
-  'Config Options': '配置选项',
   'Command Line Interface': '命令行接口',
+  'Config Options': '配置选项',
+  'Type Definitions': '类型定义',
 
   'The Elegant Bundler for Libraries': '优雅的库打包器',
 

docs/.vitepress/scripts/docs-generate.ts

@@ -1,22 +1,15 @@
-import {
-  copyFileSync,
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs'
-import { dirname } from 'node:path'
+import { cp, rm } from 'node:fs/promises'
 import * as typedoc from 'typedoc'
 
+const LANGUAGES = ['zh-CN']
+
 /**
  * Run TypeDoc with the specified tsconfig
  */
-async function runTypedoc(tsconfigPath: string): Promise<void> {
+async function runTypedoc(tsconfig: string): Promise<void> {
   // Bootstrap TypeDoc with plugins
   const app = await typedoc.Application.bootstrapWithPlugins({
-    tsconfig: tsconfigPath,
+    tsconfig,
   })
 
   // May be undefined if errors are encountered.
@@ -30,199 +23,6 @@ async function runTypedoc(tsconfigPath: string): Promise<void> {
   }
 }
 
-/**
- * Type definitions for file operations
- */
-type FileOperation = {
-  type: 'delete-lines' | 'replace' | 'prepend' | 'append'
-  lineStart?: number
-  lineEnd?: number
-  pattern?: string | RegExp
-  replacement?: string
-}
-
-type FileMapping =
-  | {
-      type: 'file'
-      source: string
-      destination: string
-      modifications?: FileOperation[]
-    }
-  | {
-      type: 'folder'
-      sourceDir: string
-      destDir: string
-      files: string[]
-      modifications?: FileOperation[]
-    }
-
-/**
- * Class to handle file operations based on mapping configurations
- */
-class FileMapper {
-  private mappings: FileMapping[]
-
-  constructor(mappings: FileMapping[]) {
-    this.mappings = mappings
-  }
-
-  /**
-   * Modify file content with various operations
-   */
-  private modifyFile(filePath: string, operations: FileOperation[]): void {
-    let content = readFileSync(filePath, 'utf-8')
-
-    for (const op of operations) {
-      if (
-        op.type === 'delete-lines' &&
-        op.lineStart !== undefined &&
-        op.lineEnd !== undefined
-      ) {
-        const lines = content.split('\n')
-        const newLines = [
-          ...lines.slice(0, op.lineStart - 1),
-          ...lines.slice(op.lineEnd),
-        ]
-        content = newLines.join('\n')
-      } else if (
-        op.type === 'replace' &&
-        op.pattern &&
-        op.replacement !== undefined
-      ) {
-        content = content.replaceAll(
-          new RegExp(op.pattern, 'g'),
-          op.replacement,
-        )
-      } else if (op.type === 'prepend' && op.replacement !== undefined) {
-        content = `${op.replacement}\n${content}`
-      } else if (op.type === 'append' && op.replacement !== undefined) {
-        content = `${content}\n${op.replacement}\n`
-      }
-    }
-
-    writeFileSync(filePath, content)
-  }
-
-  /**
-   * Ensure a directory exists, creating it if necessary
-   */
-  private ensureDir(dirPath: string): void {
-    if (!existsSync(dirPath)) {
-      mkdirSync(dirPath, { recursive: true })
-    }
-  }
-
-  /**
-   * Remove a file or directory if it exists
-   */
-  private remove(
-    path: string,
-    options = { recursive: true, force: true },
-  ): void {
-    if (existsSync(path)) {
-      rmSync(path, options)
-    }
-  }
-
-  /**
-   * Move a file from source to destination
-   * Creates destination directory if it doesn't exist
-   */
-  private moveFile(source: string, destination: string): void {
-    this.ensureDir(dirname(destination))
-    copyFileSync(source, destination)
-  }
-
-  /**
-   * Copy a directory recursively
-   */
-  private copyDir(source: string, destination: string): void {
-    this.remove(destination)
-    this.ensureDir(destination)
-    cpSync(source, destination, { recursive: true })
-  }
-
-  /**
-   * Apply standard modifications to markdown files
-   */
-  private standardizeMarkdown(
-    filePath: string,
-    additionalOps: FileOperation[] = [],
-  ): void {
-    // Common operation: remove first 6 lines
-    const operations: FileOperation[] = [
-      { type: 'delete-lines', lineStart: 1, lineEnd: 6 },
-      {
-        type: 'prepend',
-        replacement: '<!-- prettier-ignore-start -->',
-      },
-      {
-        type: 'append',
-        replacement: '<!-- prettier-ignore-end -->',
-      },
-      ...additionalOps,
-    ]
-    this.modifyFile(filePath, operations)
-  }
-
-  /**
-   * Process a single file mapping
-   */
-  private processFileMapping(mapping: FileMapping): void {
-    if (mapping.type === 'file') {
-      this.moveFile(mapping.source, mapping.destination)
-      this.standardizeMarkdown(mapping.destination, mapping.modifications)
-    } else if (mapping.type === 'folder') {
-      this.ensureDir(mapping.destDir)
-      for (const file of mapping.files) {
-        const source = `${mapping.sourceDir}/${file}.md`
-        const destination = `${mapping.destDir}/${file}.md`
-        this.moveFile(source, destination)
-        this.standardizeMarkdown(destination, mapping.modifications)
-      }
-    }
-  }
-
-  /**
-   * Copy all processed files to locale directories
-   */
-  private copyToLocales(locales: string[]): void {
-    for (const locale of locales) {
-      const localeRefDir = `./docs/${locale}/reference`
-      this.ensureDir(localeRefDir)
-
-      // Copy all files to each locale
-      for (const mapping of this.mappings) {
-        if (mapping.type === 'file') {
-          const destFile = `${localeRefDir}/${mapping.destination.split('/').pop()}`
-          this.moveFile(mapping.destination, destFile)
-        } else if (mapping.type === 'folder') {
-          const localeDestDir = `${localeRefDir}/${mapping.destDir.split('/').pop()}`
-          this.copyDir(mapping.destDir, localeDestDir)
-        }
-      }
-    }
-  }
-
-  /**
-   * Process all file mappings
-   */
-  process(locales: string[] = []): void {
-    // Process each mapping
-    for (const mapping of this.mappings) {
-      this.processFileMapping(mapping)
-    }
-
-    // Remove the original api folder
-    this.remove('./docs/reference/api')
-
-    // Copy to locales if specified
-    if (locales.length > 0) {
-      this.copyToLocales(locales)
-    }
-  }
-}
-
 /**
  * Main function to generate API reference documentation
  */
@@ -234,43 +34,15 @@ async function generateApiReference() {
   console.log('✅ Reference generated successfully!')
   console.log('📚 Beautifying reference structure...')
 
-  // Define file mappings
-  const fileMappings: FileMapping[] = [
-    {
-      type: 'file',
-      source: './docs/reference/api/interfaces/Options.md',
-      destination: './docs/reference/config-options.md',
-      modifications: [
-        {
-          type: 'replace',
-          pattern: String.raw`\.\.\/type-aliases`,
-          replacement: './type-aliases',
-        },
-        {
-          type: 'replace',
-          pattern: `Workspace.md`,
-          replacement: 'workspace.md',
-        },
-      ],
-    },
-    {
-      type: 'file',
-      source: './docs/reference/api/interfaces/Workspace.md',
-      destination: './docs/reference/workspace.md',
-    },
-    {
-      type: 'folder',
-      sourceDir: './docs/reference/api/type-aliases',
-      destDir: './docs/reference/type-aliases',
-      files: ['Sourcemap', 'Format', 'ModuleTypes'],
-    },
-  ]
+  await rm('docs/reference/api/index.md', { force: true })
+  await rm('docs/reference/api/_media', { recursive: true, force: true })
 
-  // Create a file mapper and process all mappings
-  const fileMapper = new FileMapper(fileMappings)
-  fileMapper.process(['zh-CN'])
-
-  console.log('✅ Reference structure beautified successfully!')
+  for (const language of LANGUAGES) {
+    await cp(`docs/reference/api`, `docs/${language}/reference/api`, {
+      recursive: true,
+      force: true,
+    })
+  }
 }
 
 // Execute the main function

docs/advanced/programmatic-usage.md

@@ -16,4 +16,4 @@ await build({
 })
 ```
 
-All CLI options are available as properties in the options object. See [Config Options](../reference/config-options.md) for the full list.
+All CLI options are available as properties in the options object. See [Config Options](../reference/api/Interface.Options.md) for the full list.

docs/options/config-file.md

@@ -81,4 +81,4 @@ tsdown --from-vite vitest # Load vitest.config.*
 
 ## Reference
 
-For a full list of available configuration options, refer to the [Config Options Reference](../reference/config-options.md). This includes detailed explanations of all supported fields and their usage.
+For a full list of available configuration options, refer to the [Config Options Reference](../reference/api/Interface.Options.md). This includes detailed explanations of all supported fields and their usage.