98 lines
4.3 KiB
Markdown
98 lines
4.3 KiB
Markdown
# Markdown 渲染器完善计划
|
||
|
||
## 背景
|
||
|
||
Planet 控制台当前有三类主要 Markdown 使用场景：
|
||
|
||
- 文档中心：技术文档、计划文档、运行手册。
|
||
- AI Playground：模型回复、分析结果、代码片段。
|
||
- BGP 简报：由系统生成并保存的态势报告。
|
||
|
||
这些场景都复用 `frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx`。因此 Markdown 能力应该集中在共享渲染器内完成，页面只负责传入内容、链接转换和布局约束，不能让每篇文档或每个页面手写复制按钮、表格样式、列表样式等交互细节。
|
||
|
||
## 目标
|
||
|
||
建设一个稳定、可复用、适合技术文档和 AI 输出的 Markdown 渲染器，优先覆盖常用语法、代码块操作和清晰的阅读样式，并为后续语法高亮、锚点导航、内容安全策略留出接口。
|
||
|
||
## 成功标准
|
||
|
||
- 代码块支持 fenced language、语言标签、复制按钮、复制成功状态和横向滚动。
|
||
- 常用块语法稳定渲染：标题 1-6、段落、引用、分割线、表格、无序列表、有序列表、任务列表。
|
||
- 常用行内语法稳定渲染：链接、自动链接、图片、行内代码、粗体、斜体、删除线。
|
||
- 文档中心、AI Playground、BGP 简报继续复用同一个组件，不出现页面级重复实现。
|
||
- 样式在普通业务面板和文档中心都有合理表现，文档中心可以通过 `.docs-markdown` 覆盖主题变量。
|
||
- 前端 TypeScript build 通过，`git diff --check` 无空白错误。
|
||
|
||
## 当前实施范围
|
||
|
||
### 第一阶段：共享渲染器补齐
|
||
|
||
- 在 `MarkdownRenderer` 内解析 fenced code block 的语言信息。
|
||
- 引入 `MarkdownCodeBlock` 子组件，负责语言标签、复制按钮和复制状态。
|
||
- 保留现有 `Scrollbar` 横向滚动能力，避免长代码撑破页面。
|
||
- 扩展标题渲染到 h1-h6，并保留 `getHeadingId` 对文档目录的支持。
|
||
- 扩展列表解析，支持 `-`、`*`、`+`、`1.`、`1)` 和 GitHub 风格任务列表。
|
||
- 扩展行内解析，支持图片、自动链接、删除线。
|
||
|
||
### 第二阶段：样式统一
|
||
|
||
- 全局 Markdown 样式覆盖业务场景，保持紧凑、清晰、可扫描。
|
||
- 文档中心用 `.docs-markdown` 适配主题变量，避免硬编码颜色破坏明暗主题。
|
||
- 代码块 toolbar 和 copy button 不依赖具体页面。
|
||
- 图片默认响应式展示，避免超出内容区域。
|
||
|
||
### 第三阶段：验证
|
||
|
||
- 使用前端 build 验证 TypeScript 和 Vite 构建。
|
||
- 使用 `git diff --check` 验证补丁格式。
|
||
- 手动检查至少一个文档页中代码块复制按钮、语言标签和表格滚动是否出现。
|
||
|
||
## 后续增强项
|
||
|
||
### 语法高亮
|
||
|
||
当前不新增高亮依赖，避免一次性引入过重运行时代码。后续可以在以下方案中二选一：
|
||
|
||
- `shiki`：适合文档中心，视觉质量高，但包体和初始化成本更高。
|
||
- `highlight.js`：接入简单，覆盖语言广，但样式控制需要额外约束。
|
||
|
||
建议当文档代码块数量稳定增加后再引入，并做按需加载或懒加载。
|
||
|
||
### 更完整 CommonMark 支持
|
||
|
||
当前渲染器覆盖 Planet 常见内容，不追求完整 CommonMark 兼容。后续如果需要完整规范，建议切换到成熟生态：
|
||
|
||
- `react-markdown`
|
||
- `remark-gfm`
|
||
- `rehype-sanitize`
|
||
- `rehype-slug`
|
||
|
||
切换前需要评估：链接转换、目录 ID、现有样式、AI 输出安全策略和包体影响。
|
||
|
||
### 安全策略
|
||
|
||
目前渲染器不解析原始 HTML，这是正确默认值。后续如需支持 HTML，必须先明确：
|
||
|
||
- 是否允许用户输入 Markdown。
|
||
- 是否需要 HTML 白名单。
|
||
- 是否需要 `rehype-sanitize`。
|
||
- 图片和链接是否需要域名策略。
|
||
|
||
### 文档页能力
|
||
|
||
可继续补齐：
|
||
|
||
- 标题锚点悬浮复制。
|
||
- Mermaid 图表。
|
||
- 代码块折叠。
|
||
- 文档内搜索结果定位到代码块。
|
||
- 复制按钮埋点，用于判断文档片段是否真正被使用。
|
||
|
||
## 维护约束
|
||
|
||
- Markdown 语法能力优先放在共享渲染器，不在具体文档页面散落实现。
|
||
- 文档内容只表达内容，不承载 UI 行为。
|
||
- 新增 Markdown 能力必须同时考虑文档中心、AI Playground、BGP 简报三个调用方。
|
||
- 不解析原始 HTML，除非同步引入明确的 sanitize 策略。
|
||
- 与主题相关的样式优先走页面容器变量覆盖，不在组件内写死文档中心颜色。
|