add vitepress docs

2026-09-21 16:05:14 +08:00
parent b435bf992e
commit 37cf38fe27
73 changed files with 7003 additions and 802 deletions
@@ -0,0 +1,130 @@
+import { resolve } from "node:path";
+import { defineConfig } from "vitepress";
+import {
+	componentPreview,
+	containerPreview
+} from "@vitepress-demo-preview/plugin";
+import AutoImport from "unplugin-auto-import/vite";
+import { groupByCategory, toDocLink } from "./components";
+import { docgenPlugin } from "./plugins/docgen";
+import { timiWebSsrStub } from "./plugins/ssr-stub";
+
+/** `__dirname` 由 VitePress 打包配置时注入，指向 `docs/.vitepress`。 */
+const docsDir = resolve(__dirname, "..");
+/** 仓库根目录，组件源码位于它的 `src` 下。 */
+const repoRoot = resolve(docsDir, "..");
+/** timi-web 仓库目录，docs 通过 link 依赖它。 */
+const timiWebRoot = resolve(repoRoot, "../timi-web");
+
+/**
+ * 源码引用别名。
+ *
+ * demo 直接引用 `src` 源码而非构建产物，改组件即可热更新文档。
+ * 组件源码自身的传递依赖（tiptap、prismjs 等）由 timi-web 的 node_modules 解析，
+ * docs 无需重复声明。
+ */
+const alias = {
+	"timi-tdesign-mobile": resolve(repoRoot, "src/index.ts"),
+	"timi-web/editor": resolve(timiWebRoot, "src/editor/index.ts")
+};
+
+/** 组件文档侧边栏，按 components.ts 的分类与顺序生成。 */
+const componentSidebar = groupByCategory().map(group => ({
+	text: group.category,
+	collapsed: false,
+	items: group.items.map(item => ({
+		text: item.title,
+		link: toDocLink(item)
+	}))
+}));
+
+export default defineConfig({
+	title: "timi-tdesign-mobile",
+	description: "移动端 TDesign 组件库的演示与 API 文档",
+	lang: "zh-CN",
+	cleanUrls: true,
+
+	themeConfig: {
+		nav: [
+			{ text: "指南", link: "/guide/" },
+			{ text: "场景", link: "/scenarios/editor" },
+			{ text: "组件", link: "/components/" }
+		],
+		sidebar: [
+			{
+				text: "指南",
+				items: [
+					{ text: "快速开始", link: "/guide/" },
+					{ text: "演示与文档约定", link: "/guide/demo" }
+				]
+			},
+			{
+				text: "场景示例",
+				collapsed: false,
+				items: [
+					{ text: "编辑器能力总览", link: "/scenarios/editor" },
+					{ text: "文章编辑与预览", link: "/scenarios/article" },
+					{ text: "通知编辑与预览", link: "/scenarios/notify" },
+					{ text: "移动端组件", link: "/scenarios/mobile" },
+					{ text: "AI 对话", link: "/scenarios/ai" }
+				]
+			},
+			...componentSidebar
+		],
+		outline: {
+			level: [2, 3],
+			label: "本页目录"
+		},
+		search: {
+			provider: "local"
+		},
+		docFooter: {
+			prev: "上一篇",
+			next: "下一篇"
+		},
+		darkModeSwitchLabel: "主题",
+		sidebarMenuLabel: "目录",
+		returnToTopLabel: "回到顶部"
+	},
+
+	markdown: {
+		theme: {
+			light: "vitesse-light",
+			dark: "vitesse-dark"
+		},
+		lineNumbers: true,
+		config(md) {
+			// 组件依赖浏览器 API（Tiptap、Prism、ResizeObserver、SSE 等），
+			// 统一开启 clientOnly 交给浏览器渲染，避免 SSR 阶段报错。
+			md.use(componentPreview, { clientOnly: true, alias });
+			md.use(containerPreview, { clientOnly: true, alias });
+		}
+	},
+
+	vite: {
+		resolve: {
+			alias
+		},
+
+		plugins: [
+			// 必须最先执行：SSR 阶段拦截 timi-web，否则整个构建无法通过。
+			timiWebSsrStub(docsDir),
+			docgenPlugin(repoRoot),
+			// src 源码依赖自动导入（内部没有显式 import vue 的文件不在少数），
+			// 这里仅为其提供支持；docs 自身的代码一律显式导入。
+			AutoImport({
+				imports: ["vue"],
+				dts: false
+			})
+		],
+
+		server: {
+			port: 3004,
+			host: true,
+			fs: {
+				// demo 需要读取 docs 之外的 src 与 timi-web 源码。
+				allow: [repoRoot, timiWebRoot]
+			}
+		}
+	}
+});