feat(docs): build maintainable documentation site

2026-07-13 15:38:47 +08:00
parent 72bfba2d4d
commit d2f810e9fe
52 changed files with 2380 additions and 2224 deletions
@@ -0,0 +1,142 @@
+/** VitePress configuration for the locally projected documentation site. */
+
+import type { DefaultTheme, PageData } from 'vitepress'
+import type { ViteDevServer } from 'vite'
+import { withMermaid } from 'vitepress-plugin-mermaid'
+import { docsPages, type DocsPage } from '../docs.ts'
+import { docsSourceFiles, projectDocs } from '../../scripts/project-doc-site.ts'
+
+projectDocs()
+
+const sectionOrder = [
+  '入门',
+  '基础',
+  '框架能力',
+  '实战',
+  'Concepts',
+  'Generated reference',
+  'Data structures',
+  'Cookbook',
+]
+
+function sidebar(collection: DocsPage['sidebar']): DefaultTheme.SidebarItem[] {
+  const pages = docsPages.filter(page => page.sidebar === collection && page.route !== 'index.md')
+  const sections = new Map<string, DocsPage[]>()
+  for (const page of pages) {
+    const entries = sections.get(page.section) ?? []
+    entries.push(page)
+    sections.set(page.section, entries)
+  }
+  return [...sections.entries()]
+    .sort(([left], [right]) => sectionOrder.indexOf(left) - sectionOrder.indexOf(right))
+    .map(([text, entries]) => ({
+      text,
+      items: entries
+        .sort((left, right) => left.order - right.order)
+        .map(page => ({ text: page.label, link: `/${page.route.replace(/(?:index)?\.md$/, '')}` })),
+    }))
+}
+
+function watchCanonicalDocs(server: ViteDevServer): void {
+  const sources = docsSourceFiles()
+  server.watcher.add(sources)
+  server.watcher.on('change', (changed) => {
+    if (!sources.includes(changed)) return
+    projectDocs()
+  })
+}
+
+function escapeVueInterpolation(html: string): string {
+  return html.replaceAll('{{', '&#123;&#123;').replaceAll('}}', '&#125;&#125;')
+}
+
+const sharedTheme: Pick<DefaultTheme.Config, 'search' | 'socialLinks' | 'editLink'> = {
+  search: { provider: 'local' },
+  socialLinks: [
+    { icon: 'github', link: 'https://github.com/deepseek-harness/deepseek-harness' },
+  ],
+  editLink: {
+    pattern: ({ frontmatter }: PageData) => {
+      const data: unknown = frontmatter
+      const editSource: unknown = typeof data === 'object' && data !== null ? Reflect.get(data, 'editSource') : undefined
+      if (typeof editSource !== 'string') throw new Error('Projected documentation page has no editSource frontmatter.')
+      return `https://github.com/deepseek-harness/deepseek-harness/edit/master/${editSource}`
+    },
+    text: '在 GitHub 上编辑此页',
+  },
+}
+
+export default withMermaid({
+  title: 'DeepSeek Harness',
+  description: '用于构建 Agent Harness 的插件化 SDK',
+  cleanUrls: true,
+  srcDir: '.generated',
+  cacheDir: '.cache',
+  outDir: '.dist',
+  locales: {
+    root: {
+      label: '简体中文',
+      lang: 'zh-CN',
+      themeConfig: {
+        nav: [
+          { text: '入门', link: '/guide/', activeMatch: '^/guide/' },
+          { text: '开发', link: '/develop/basic/', activeMatch: '^/develop/' },
+          { text: 'Reference', link: '/en/', activeMatch: '^/en/' },
+        ],
+        sidebar: {
+          '/guide/': sidebar('zh-guide'),
+          '/develop/': sidebar('zh-develop'),
+        },
+        outline: { label: '本页目录' },
+        docFooter: { prev: '上一篇', next: '下一篇' },
+      },
+    },
+    en: {
+      label: 'English',
+      lang: 'en-US',
+      link: '/en/',
+      themeConfig: {
+        nav: [
+          { text: 'Concepts', link: '/en/' },
+          { text: 'Reference', link: '/en/config-catalog' },
+          { text: '中文指南', link: '/guide/' },
+        ],
+        sidebar: {
+          '/en/': sidebar('en-docs'),
+        },
+        editLink: {
+          pattern: ({ frontmatter }: PageData) => {
+            const data: unknown = frontmatter
+            const editSource: unknown = typeof data === 'object' && data !== null ? Reflect.get(data, 'editSource') : undefined
+            if (typeof editSource !== 'string') throw new Error('Projected documentation page has no editSource frontmatter.')
+            return `https://github.com/deepseek-harness/deepseek-harness/edit/master/${editSource}`
+          },
+          text: 'Edit this page on GitHub',
+        },
+        outline: { label: 'On this page' },
+        docFooter: { prev: 'Previous', next: 'Next' },
+      },
+    },
+  },
+  vite: {
+    plugins: [
+      {
+        name: 'deepseek-harness-doc-projector',
+        configureServer: watchCanonicalDocs,
+      },
+    ],
+  },
+  markdown: {
+    config(md) {
+      const renderText = md.renderer.rules.text
+      const renderCode = md.renderer.rules.code_inline
+      if (renderText === undefined || renderCode === undefined) {
+        throw new Error('VitePress Markdown renderer is missing its text or inline-code rule.')
+      }
+      md.renderer.rules.text = (...args) => escapeVueInterpolation(renderText(...args))
+      md.renderer.rules.code_inline = (...args) => escapeVueInterpolation(renderCode(...args))
+    },
+  },
+  mermaid: {},
+  themeConfig: sharedTheme,
+})