tl-docs-viewer-create

用途

tl-docs-viewer-create 用于为管理后台创建可浏览的文档查看器。当需要为现有管理区域添加 docs/ 浏览器、在应用内查看 Markdown 文档，或需要文档查看器组件时使用。触发短语包括「create docs viewer」「add documentation browser」「admin docs UI」「browse docs folder」「docs viewer component」。

主要能力

技能产出以下内容：

三栏布局（树 + 内容 + 目录）的 React 页面组件
用于树结构和内容的服务端 API 端点
配套组件：DocTree、MermaidMarkdown、OnThisPageNav
关于路由放置和库选择的决策

架构上默认采用三栏布局：左侧 DocTree（250px）展示文档树，中间 DocContent（flex-1）渲染 Markdown 内容，右侧 OnThisPage（200px）展示目录。数据流为：DocsViewerPage 分别驱动 DocTree、DocContent、OnThisPageNav；DocTree 选择后经 Router 触发路径变化，Content 随之更新；Tree 和 Content 分别请求服务端 API。

使用方式

技能在实现前通过结构化提问收集项目上下文，问题流程为：触发技能 → 扫描管理后台模式 → 询问管理区域 → 询问前端技术栈 → 询问路由位置 → 询问布局模式 → 询问库偏好 → 实现查看器。

问题摘要：

管理区域检测 — 是否已有管理区域？（yes/no/scan）
前端技术栈 — React Router / Wouter / Next.js / TanStack Router / Remix
路由位置 — 检测到的路径 / /admin/docs / /docs / 自定义
布局模式 — 三栏 / 两栏 / 单栏
库偏好 — Markdown 渲染器 + 数据获取选择

实现分三个阶段：

阶段 1：服务端 API

创建两个端点：

GET /admin/docs/tree — 以 JSON 树返回文件夹结构，接口为 DocNode { name, path, type: 'file' | 'folder', children? }
GET /admin/docs/content/:path* — 返回 Markdown 内容与元数据，接口为 DocContent { content, title, lastUpdated?, path }

阶段 2：React 组件

创建组件层级：AdminDocsLayout（三栏布局包装器）、DocTree（递归树导航）、DocTreeItem（带展开/折叠的单个树节点）、MermaidMarkdown（支持 Mermaid 的 Markdown 渲染器）、OnThisPageNav（从标题生成的目录）。

阶段 3：集成

路由设置按前端技术栈区分：

React Router：<Route path="/admin/docs/*" element={<DocsViewer />} />
Wouter：<Route path="/admin/docs/:path*" component={DocsViewer} />
Next.js：app/admin/docs/[[...path]]/page.tsx
TanStack Router：createRoute({ path: '/admin/docs/$path', component: DocsViewer })

数据获取按库偏好区分：TanStack Query 使用 useQuery({ queryKey: ['docs', 'tree'], queryFn: fetchTree })；SWR 使用 useSWR('/admin/docs/tree', fetcher)；原生 fetch 使用 useEffect + useState 模式。

依赖项可通过 AskQuestion 配置：Markdown 默认 @uiw/react-markdown-preview，备选 react-markdown、marked；数据获取默认 @tanstack/react-query，备选 swr、原生 fetch；图表使用 mermaid（可选）。

Markdown 渲染

推荐使用 Streamdown（流式优化的 React Markdown 渲染器，内置 Shiki 和 Mermaid 支持）：

import { Streamdown } from 'streamdown';
import { code } from '@streamdown/code';
import { mermaid } from '@streamdown/mermaid';

<Streamdown 
  mode="static" 
  plugins={{ code, mermaid }}
  shikiTheme={['github-light', 'github-dark']}
>
  {content}
</Streamdown>

Tailwind v4 需在 globals.css 添加：

@source "../node_modules/streamdown/dist/*.js";
@source "../node_modules/@streamdown/code/dist/*.js";
@source "../node_modules/@streamdown/mermaid/dist/*.js";

关键属性：mode（"streaming" | "static"，文档用 static）、plugins（{ code?, mermaid?, math? }）、shikiTheme（[light, dark]）、controls（boolean，复制按钮）。

备选方案 react-markdown：

import ReactMarkdown from 'react-markdown';
import rehypeHighlight from 'rehype-highlight';
import remarkGfm from 'remark-gfm';

<ReactMarkdown
  remarkPlugins={[remarkGfm]}
  rehypePlugins={[rehypeHighlight]}
>
  {content}
</ReactMarkdown>

搜索集成

Pagefind（静态搜索）适合预构建文档，构建时索引、客户端搜索：

import { search } from '@pagefind/default-ui';
const results = await search(query);

Flexsearch（客户端搜索）适合运行时加载的动态文档：

import FlexSearch from 'flexsearch';
const index = new FlexSearch.Index();
docs.forEach((doc, id) => index.add(id, doc.content));
const results = index.search(query);

搜索模态框模式提供 SearchModal 组件示例，包含输入框与结果列表。

键盘导航

必需快捷键：/ 或 Cmd+K 打开搜索；Esc 关闭搜索/模态框；↑ ↓ 导航结果；Enter 选择结果；j k 导航树（可选）。实现通过 useEffect 监听 keydown 事件。

无障碍

ARIA 要求包括：<nav aria-label="Documentation navigation"> 包裹 role="tree" 的列表，树项使用 role="treeitem" 与 aria-expanded、aria-selected；内容区使用 role="main"；目录使用 aria-label="On this page"。焦点管理通过 focusedIndex 状态与 ArrowDown/ArrowUp/Enter 键处理。

MDX 支持

对于带嵌入组件的交互式文档，使用 @mdx-js/mdx 的 compile 与 run 渲染，可注册自定义组件如 CodePlayground、Callout、Steps。

文档写作指南

来自 remotion-dev 模式：每页一个 API；不要假设简单（避免「simply」「just」）；以「you」称呼；保持简洁；字段用标题而非项目符号；代码块始终加标题。

验证

实现后需验证：树加载并显示文件夹结构；点击文件加载 Markdown 内容；Mermaid 图表渲染（若启用）；目录从标题生成；路由导航正常；支持深色模式（若适用）。

限制

资料未提供该技能的具体收费、价格、平台限制或性能数据。

技能介绍

用途