# 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 策略。 - 与主题相关的样式优先走页面容器变量覆盖，不在组件内写死文档中心颜色。