planet/docs/plans/frontend-public-docs-site-plan.md

Frontend Public Docs Site Plan

目标

新增一个公开访问的 /docs 页面，作为 Planet 的开发设计文档与使用手册入口。

这个页面应类似常见开源软件文档站：

• 不需要登录即可访问
• 与 /earth 和 admin 后台平级，但视觉和信息架构独立
• 直接整理并展示仓库内 docs/technical 的 Markdown 文档
• 支持搜索、分类导航、文档目录和内部跳转
• 让 docs/technical 继续作为文档真源，避免页面内容和仓库文档漂移

非目标

本阶段不做：

• 后端全文搜索服务
• 数据库驱动的 CMS
• 独立文档构建系统，例如 Docusaurus / VitePress
• 每篇文档单独手写 React 页面
• 用户权限、编辑器、在线保存或评论功能
• 把 docs/plans、docs/deprecated 全量公开为正式手册

后续可以再决定是否把 plans / deprecated 做成独立的“路线图 / 历史归档”分区。

技术路线

推荐方案：Markdown 直接渲染

使用 Vite 在前端构建阶段直接加载 docs/technical/**/*.md：

const modules = import.meta.glob('../../../docs/technical/**/*.md', {
  query: '?raw',
  import: 'default',
})

这样每篇 Markdown 文件仍然留在仓库文档目录中，/docs 页面只是读取、索引和渲染这些文档。

当前项目已经满足主要前提：

• 前端使用 Vite + React
• frontend/vite.config.ts 已配置 server.fs.allow: ['..']
• 已有 MarkdownRenderer 可作为基础
• docs/technical 文档数量较少，前端本地搜索足够

不推荐方案：每篇文档单独写 React

不建议把每篇文档重写成 .tsx 页面，因为：

• 文档会出现两份真源
• 修改技术文档时还要同步 UI 页面
• 计划文档、技术上下文、变量表这类内容天然适合 Markdown
• 后续新增文档的成本会变高

只有当某篇文档需要强交互演示、实时图表或复杂 UI 时，才考虑给该文档补充一个 React 组件扩展。

信息架构

公开路由

新增：

• /docs
• /docs/:slug

路由行为：

• /docs 默认打开 docs/technical/README.md，或打开人工指定的首页文档
• /docs/:slug 打开对应技术文档
• 未找到文档时显示 docs 专属 404，而不是跳回 admin
• /docs 加入 App.tsx 的公开路由白名单

文档分类

将 docs/technical 中的现有文档整理进以下分组：

Overview

• README.md

Earth

• earth-frontend-context.md
• earth-layer-style-reference.md
• earth-render-layer-order.md
• earth-satellite-footprint-policy.md
• earth-bgp-context.md
• earth-news-live-streams-collector-format.md

Frontend

• frontend-admin-frontend-context.md
• frontend-layout-guidelines.md

Backend

• backend-collectors.md
• backend-system-service-control.md

Agents

• agents-aiprovider.md

Ops

• ops-docker-compose-buildx-upgrade.md

页面布局

桌面端：

• 顶部：产品名、搜索框、当前文档标题
• 左侧：文档分组导航
• 中间：Markdown 正文
• 右侧：当前文档目录，也就是 h2 / h3 anchors

移动端：

• 顶部固定搜索入口
• 导航折叠为抽屉或下拉
• 正文单列显示
• 当前文档目录折叠为“本文目录”

视觉风格：

• 像开源软件 docs 页面，清晰、安静、可长时间阅读
• 不复用 admin 后台的重操作感布局
• 不做 Earth 的沉浸式深色 HUD 风格
• 优先阅读性、扫描效率和代码/表格可读性

前端实现设计

文件结构

建议新增：

frontend/src/pages/Docs/
  Docs.tsx
  docs-content.ts
  docs-search.ts
  docs-slugs.ts
  Docs.css

可选拆分：

frontend/src/pages/Docs/components/
  DocsSidebar.tsx
  DocsSearch.tsx
  DocsToc.tsx
  DocsMarkdown.tsx

如果初版代码量不大，可以先保持在 Docs.tsx + 少量 helper 文件中，避免过度拆分。

文档注册表

创建一个 registry，负责将 Markdown 文件路径映射为文档元信息：

interface DocsEntry {
  slug: string
  path: string
  title: string
  group: string
  order: number
  loader: () => Promise<string>
}

slug 规则：

• docs/technical/README.md -> overview
• docs/technical/earth-layer-style-reference.md -> earth-layer-style-reference
• 只暴露稳定 slug，不暴露本机绝对路径

标题规则：

• 优先读取 Markdown 第一个 # heading
• 没有 h1 时用人工 registry title
• 再 fallback 到文件名转换标题

Markdown 渲染

初版可以复用现有：

• frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx

但建议增强或包装为 docs 专用渲染：

• heading 生成稳定 id
• 右侧 TOC 使用同一套 heading 解析结果
• 内部 Markdown 链接转换为 /docs/:slug
• 外部链接保留 target="_blank" rel="noreferrer"
• 表格横向滚动
• 代码块保留等宽字体和语言标记
• 支持 GitHub 风格的相对文档链接

内部链接转换示例：

• earth-render-layer-order.md -> /docs/earth-render-layer-order
• ./earth-layer-style-reference.md -> /docs/earth-layer-style-reference
• /home/ray/dev/linkong/planet/docs/technical/foo.md -> /docs/foo

对非 docs/technical 的链接：

• 初版可保留原始链接文本
• 或显示为不可跳转的 repo path
• 后续再扩展为跨文档区导航

搜索

初版使用纯前端本地搜索。

索引字段：

• title
• slug
• group
• headings
• markdown 正文纯文本

搜索策略：

• 页面首次加载后异步加载所有 docs/technical Markdown
• 生成内存索引
• 用户输入时本地过滤
• 简单打分即可：
  • 标题命中权重最高
  • heading 命中其次
  • 文件名 / slug 命中其次
  • 正文命中最低

搜索结果展示：

• 文档标题
• 分组
• 命中的 heading 或正文摘要
• 点击跳转到文档

当前只有 13 篇文档，不需要 Lunr、Fuse 或后端搜索。后续文档数量显著增长时，再考虑引入轻量搜索库。

路由接入

修改：

• frontend/src/App.tsx

新增 lazy import：

const Docs = lazy(() => import('./pages/Docs/Docs'))

公开路由：

const publicPaths = new Set(['/', '/earth', '/docs'])

注意：/docs/:slug 不能只用精确匹配 Set。

建议改为：

const isPublicRoute =
  window.location.pathname === '/' ||
  window.location.pathname === '/earth' ||
  window.location.pathname === '/docs' ||
  window.location.pathname.startsWith('/docs/')

新增 routes：

<Route path="/docs" element={<Docs />} />
<Route path="/docs/:slug" element={<Docs />} />

样式

建议独立 Docs.css，不依赖 admin 页面布局。

核心样式要求：

• 文档正文最大宽度控制在适合阅读的范围
• 表格横向滚动，不撑破布局
• 代码块横向滚动
• 左侧导航固定或 sticky
• 右侧 TOC sticky
• 移动端隐藏右侧 TOC，导航折叠
• 搜索结果浮层或独立面板不遮挡正文阅读

注意：

• 不做营销 hero
• 不做卡片堆叠式首页
• 首页第一屏应直接是文档入口和内容，而不是宣传页

实施阶段

Phase 1：基础文档站

目标：

• /docs 可公开访问
• 能看到 docs/technical 文档列表
• 能打开每篇 Markdown
• 能基本渲染标题、段落、列表、代码块、表格

任务：

• 新增 Docs 页面
• 新增 docs registry
• 接入 Vite raw Markdown loading
• 接入 /docs 和 /docs/:slug
• 加入公开路由白名单
• 初版 CSS 布局

验收：

• 未登录访问 /docs 不跳转登录
• /docs/earth-layer-style-reference 可打开样式参考文档
• /docs/backend-collectors 可打开后端采集器文档
• 构建通过：source ~/.zshrc && bun run build

Phase 2：搜索与 TOC

目标：

• 支持本地搜索所有 technical 文档
• 当前文档右侧显示目录
• 搜索结果可跳转

任务：

• 实现 heading parser
• 实现 TOC 组件
• 实现 search index
• 搜索结果显示文档标题、分组和摘要
• 当前文档标题与 active nav 高亮

验收：

• 搜索 Fresnel 能找到 Earth 图层样式文档
• 搜索 collector 能找到 backend collectors
• 点击搜索结果进入对应文档
• 右侧 TOC 点击后滚动到对应 heading

Phase 3：链接清理与文档体验

目标：

• Markdown 内部链接在 docs 站内自然跳转
• 长表格、代码块、绝对路径链接的显示更友好

任务：

• 转换 docs/technical/*.md 相对链接
• 转换 repo 内 technical 文档绝对路径
• 外链新窗口打开
• 文件路径链接以代码样式显示
• 增强空状态和 404

验收：

• 从 docs/technical/README.md 点击 technical 文档链接进入 /docs/:slug
• 不支持的 repo 内路径不会导致前端崩溃
• 外部链接行为正常

Phase 4：文档内容整理

目标：

• docs/technical 的首页适合作为公开手册入口
• 每篇文档标题、摘要和分类清晰

任务：

• 检查每篇文档是否有唯一 h1
• 给 README 补公开手册导览
• 必要时补文档摘要
• 保持文档内容仍然服务开发维护，不改成营销语气

验收：

• /docs 首页能说明各技术文档用途
• 左侧分类和 README 内容一致
• 没有明显重复、过期或找不到的主入口

需要改动的文件

预计新增：

• frontend/src/pages/Docs/Docs.tsx
• frontend/src/pages/Docs/Docs.css
• frontend/src/pages/Docs/docs-content.ts
• frontend/src/pages/Docs/docs-search.ts

预计修改：

• frontend/src/App.tsx
• frontend/src/components/MarkdownRenderer/MarkdownRenderer.tsx 或新增 docs 专用 wrapper
• docs/technical/README.md

可选修改：

• frontend/src/index.css，只放全局极少量 docs shell reset 时才需要
• docs/CHANGELOG.md，实施完成后记录
• docs/version-history.md，若进入版本发布流程再更新

风险与注意事项

构建路径风险

Vite 从 frontend/src 读取 ../../../docs/technical/**/*.md 时，需要确认开发和生产构建都可解析。

缓解：

• 使用相对路径 glob
• 构建验证必须跑 source ~/.zshrc && bun run build
• 不使用运行时 fetch('/docs/...') 读取仓库文件，避免生产环境缺文件

Markdown 能力不足

现有 MarkdownRenderer 是轻量实现，可能不完整支持所有 GitHub Markdown。

缓解：

• 初版优先覆盖当前 docs/technical 实际用到的语法
• 若后续需要脚注、嵌套列表、复杂代码高亮，再考虑引入 react-markdown 等依赖

Bundle 体积

把所有 Markdown 打进前端 bundle 会增加体积。

当前文档数量少，风险可接受。

缓解：

• 使用 lazy page chunk
• Markdown loader 保持异步
• 搜索索引在 /docs 页面内初始化，不影响 /earth 和 admin 首屏

公开内容边界

docs/technical 会被公开展示，需要避免包含密钥、内部机器地址、临时方案或不应公开的操作细节。

缓解：

• 实施前快速审阅 docs/technical
• 暂不公开 docs/plans 和 docs/deprecated
• 以后如需公开更多文档，先建立 allowlist

验收清单

• /docs 未登录可访问
• /docs/:slug 未登录可访问
• /docs 不影响 /earth
• 未登录访问 admin 仍然跳登录
• 左侧导航包含所有 docs/technical 文档
• 文档按 Overview / Earth / Frontend / Backend / Agents / Ops 分类
• Markdown 表格正常显示并可横向滚动
• 代码块正常显示并可横向滚动
• 搜索可搜索标题、heading 和正文
• 搜索结果点击可跳转
• 当前文档 TOC 可跳转
• 不存在的 slug 显示 docs 404
• source ~/.zshrc && bun run build 通过

后续增强

• 给文档页面增加复制 heading 链接按钮
• 给代码块增加复制按钮
• 增加“上一页 / 下一页”导航
• 增加最近更新信息
• 从 git metadata 读取文档更新时间
• 引入轻量全文搜索库
• 支持 plans / deprecated 独立分区
• 增加页面内反馈入口