Web 文档系统 (VitePress)

1. 核心技术栈清单与职责说明

架构层级	推荐选型	职责与功能定位说明
文档构建底盘	VitePress (Vue 3)	Vue 官方首推的 Docs-as-Code 静态站点生成器（SSG），基于 Vite 驱动秒级增量冷启动与纯静态 HTML 直出
内容排版扩展	Markdown (扩展语法) + markdown-it-mathjax3	官方高级排版引擎，支持 GitHub 风格 Alert 容器、代码高亮、行内及块级 LaTeX 学术数学公式渲染
离线中文全文检索	VitePress Local Search (minisearch 中文分词调优)	纯客户端离线分词检索，注入中文滑动切词规则，0 外部网络服务依赖，毫秒级高亮匹配中英文技术术语
架构图即代码	vitepress-plugin-mermaid (Mermaid.js)	将架构图表纳管为代码，在 Markdown 中直接声明流程图、时序图、状态图与 ERD，构建期自动渲染为矢量 SVG
组件演练与代码折叠	vitepress-plugin-demoblock (或同级演示容器)	提供“组件实时交互运行 + 源码折叠展开 + 一键复制代码”标准化容器，支撑企业级 UI 组件库与设计系统文档化
动态组件宿主	Vue 3 单文件组件 (.vue)	允许在 Markdown 正文中直接内嵌任意 Vue 3 业务组件，实现动态数据演示与前端 API 交互演练
工程协同与溯源	Git 提交元数据 (lastUpdated) + editLink	自动从 Git Commit 提取精准更新时间，生成一键直达 GitLab/GitHub 源码仓库提 PR 修正链接
国际化与站点地图	多语言国际化 (locales) + 自动 sitemap	标准化中英多语言目录映射；构建期自动生成 sitemap.xml，赋能企业内网检索爬虫与外部搜索引擎收录

2. 核心选型考量与技术优势

• Docs-as-Code 现代标杆与极速纯静态直出：
  • 基于 Vite 驱动的 SSG 模式，打包产物为纯静态 HTML/JS/CSS，全球边缘 CDN 零配置秒级部署；
  • 开箱自带现代化暗黑模式、响应式侧边栏、阅读进度指示与平滑页面锚点跳转。
• 中文精准分词与本地离线检索深度适配 (MiniSearch 调优)：
  • 彻底消灭默认西文空格分词导致的中文名词检索失灵痛点；
  • 针对中文技术词汇（如“分布式事务”、“数据字典”）深度配置 MiniSearch 中文分词规则，纯本地 0 外部依赖实现毫秒级即搜即得。
• 架构图即代码与版本受控协作 (Diagrams-as-Code)：
  • 集成 Mermaid 插件，将系统拓扑、业务调用时序与状态机直接以文本代码形式维护在 Markdown 中；
  • 告别繁琐痛苦的手工画图、切图与重复上传，所有架构图与文档同步享受 Git 历史提交审查与版本 Diff 追踪。
• 文档即代码与组件在线交互演练 (demoblock)：
  • 引入标准化组件演示容器，支持在同一页面内同时呈现“可操作的实时运行组件”与“折叠高亮的底层源码”，并支持一键复制代码；
  • 完美承载企业内部前端组件库、设计系统（Design System）与通用 SDK 接口展示手册的双重使命。
• 学术级数学公式与全场景排版扩展：
  • 原生支持 LaTeX 数学公式渲染（mathjax3 / KaTeX），完美排版 AI 大模型算法原理、金融风控与复杂计费模型；
  • 配合代码块高亮（Shiki）、任务清单（Task Lists）与多类型容器（Tip / Warning / Danger），满足严苛的工程白皮书排版规范。
• 企业级文档工程协同与溯源闭环：
  • 自动化挂载 Git 最后更新时间戳与“在 GitHub/GitLab 上编辑此页”链接，消灭年久失修的技术陈旧文档；
  • 内置标准国际化多语言路由与自动 sitemap.xml 生成，保障知识资产的规范流转与全域检索。

3. 适用业务场景

• 企业级技术规范矩阵、架构白皮书、研发团队知识库与新人入职手册；
• 企业内部前端业务组件库、统一设计系统（Design System）展示与演练平台；
• 开源项目官方文档中心、对外开放 RESTful / RPC 接口契约说明中心。

4. 局限性与权衡说明

• 局限性：专注于结构化文档与技术指南，不适合承载论坛、社区、问答等高频即时互动的动态 UGC 系统。
• 权衡建议：企业若需搭建重度互动的员工综合社区，应选用专职的社区/论坛系统；纯知识传递与工程规范，坚决立足 VitePress。