简单文档
功能与路线图
Estel Docs 当前已经实现的功能、边界与后续可扩展方向。
项目定位
Estel Docs 是一个中文文档与博客系统，核心目标是：
- 用 Markdown 管理文档和博客。
- 用 Nuxt Content 组织内容集合。
- 用 Nuxt UI 与自定义组件提升阅读体验。
- 用现代工程化手段完成构建、部署和维护。
- 在个人站、项目站和团队知识库之间保持可扩展性。
已实现功能总览
| 模块 | 已实现能力 |
|---|---|
| 文档系统 | docs 集合、侧边栏、目录、编辑链接、问题反馈、上一篇/下一篇。 |
| 博客系统 | blog 集合、文章列表、日期排序、分页、分类标签、封面图。 |
| Markdown | MDC、GFM、Mermaid、数学公式、代码高亮、自定义内容组件。 |
| 搜索 | 全站搜索覆盖 docs 与 blog。 |
| 主题 | 浅色/深色/系统、字体、字号、主题色、自定义色、localStorage 持久化。 |
| SEO | 页面 meta、OG 图片、Twitter Card、站点名配置。 |
| LLM | nuxt-llms 生成面向 LLM 的入口，当前主要覆盖 docs 集合。 |
| 分享 | 复制链接、查看 Markdown、ChatGPT/Claude 打开、微信分享签名。 |
| 部署 | Nuxt build/generate、Docker 多阶段构建、Coolify 部署触发。 |
| 安全 | CSP、HSTS、Referrer-Policy、Permissions-Policy、移除 X-Powered-By。 |
| 工程化 | ESLint、typecheck、Go tests、Renovate、GitHub Actions。 |
现有功能详解
1. 内容集合
content.config.ts 定义了两个集合：
docs：文档页集合，来源为docs/**。blog：博客页集合，来源为blog/**。
文档和博客都保留 rawbody，因此可以支持原始 Markdown 展示。博客额外要求 img 与 date 字段，用于列表封面和时间排序。
2. 文档阅读
文档页位于 /docs/**，支持：
- 自动查询对应路径的文档内容。
- 从导航树推导页面 headline。
- 自动生成页面目录。
- 页面底部显示编辑与问题反馈入口。
- 上一篇/下一篇 surround navigation。
- 自定义页面链接按钮。
- 自定义 OG 图片组件。
3. 博客阅读
博客页位于 /blog/**，支持：
- 列表页按日期倒序展示。
- 每页 12 篇文章，最多 15 页。
- 从路径提取分类标签。
- 缺省封面图兜底。
- 详情页展示发布时间、目录、页面操作与上下篇。
4. 原始 Markdown
/raw/** 会根据路径自动判断 docs 或 blog 集合，展示 rawbody 并支持复制全文。
该能力适合：
- 将文档发送给 AI 阅读。
- 复制原文做二次编辑。
- 对比渲染内容与源 Markdown。
5. 页面操作
页面头部操作区支持：
- 复制当前链接。
- 查看 Markdown。
- 在 ChatGPT 中打开当前 Markdown 链接。
- 在 Claude 中打开当前 Markdown 链接。
- 按需挂载微信分享组件。
这些操作都围绕当前页面 URL 与 /raw/**.md URL 生成。
6. 微信分享
微信分享由两部分组成：
- 前端
wxShare.vue：加载微信 JSSDK、请求签名、调用分享 API。 - Go 服务
wechat-sign-server/：缓存 token/ticket，校验域名，生成签名。
生产部署时，需要将站点同源的 /api/wechat/ 反向代理到 Go 服务。
7. 主题系统
useTheme.ts 是主题系统的单例 composable，负责：
- 状态管理。
- localStorage 持久化。
- 将字体、字号、主题色写入 DOM/CSS 变量。
- 提供重置设置方法。
ThemeSettings.vue 提供可视化设置面板。
8. 安全与部署
nuxt.config.ts 中统一配置安全响应头，并定义预渲染策略。Dockerfile 将依赖安装、构建和运行拆分为三个阶段，CI 会先执行质量检查，再构建镜像并在 main 分支触发部署。
当前边界
以下内容尚未实现，不要误认为是当前功能：
- 真实用户认证后端。
- 评论系统。
- RSS/Atom Feed。
- Sitemap 与 robots.txt。
- PWA / 离线阅读。
- 多语言 i18n。
- 前端单元测试与 E2E 测试。
- 生产监控、错误追踪与性能看板。
- 在线 Markdown 编辑器。
- 文档版本控制。
路线图
P0：基础补齐
这些功能成本较低，且能明显提升站点完整度。
- Sitemap：从 docs/blog 内容集合生成 sitemap。
- robots.txt：明确允许搜索引擎抓取公开内容。
- RSS/Atom：为博客提供订阅。
- 内容链接检查：CI 中检查 Markdown 内链、外链、图片引用。
- frontmatter 检查：对 docs/blog 必填字段给出更明确的错误。
- 阅读时长：按文章字数估算阅读时间。
- 面包屑导航：提升文档层级导航体验。
P1：质量与体验
- Vitest 单元测试：覆盖 composables、utils 与关键组件逻辑。
- Nuxt Test Utils：覆盖页面渲染、内容查询、路由行为。
- Playwright E2E：覆盖搜索、主题设置、博客分页、raw 页面。
- 标签/分类页：为博客生成分类索引与标签筛选。
- 代码主题接入：将设置面板中的代码主题真正联动到代码块渲染。
- 图注格式接入：让图片 title/alt 的展示规则可配置。
- 复制代码/标题锚点体验优化：增强技术文档阅读效率。
P2：运营与增长
- 隐私友好统计：接入 Umami、Plausible 或自托管分析。
- 评论系统：评估 Giscus、Utterances 或自建评论接口。
- PWA 离线阅读：缓存核心文档与静态资源。
- Lighthouse CI：监控性能、SEO、可访问性。
- 错误追踪：接入 Sentry 或等价方案。
- 部署健康检查：Docker
HEALTHCHECK与平台探针。 - 镜像与依赖安全扫描：Trivy、pnpm audit、CodeQL/SAST。
P3：产品化能力
- 认证系统：为现有登录/注册 UI 接入真实后端。
- 在线编辑器：支持 Markdown 编辑、预览、草稿与发布。
- 内容版本：多版本文档、修订历史、回滚。
- 多语言内容：支持中英双语或多语言站点。
- 高级搜索：预构建索引、服务端搜索、语义搜索或问答式搜索。
- 导出能力：PDF、EPUB、单页离线包。
- 团队协作：权限、审核、评论、变更记录。
优先级建议
推荐按以下顺序推进：
- Sitemap、robots.txt、RSS：补齐公开内容站点基础设施。
- 内容校验与前端测试：提高长期维护稳定性。
- 博客分类/标签、阅读时长、面包屑：增强内容发现与阅读体验。
- PWA、分析、评论：开始运营化。
- 认证、在线编辑、多语言、版本控制：进入产品化阶段。
实施注意事项
- 新功能应先确认是文档站能力、博客能力、运营能力还是产品化能力，避免一次性耦合过多模块。
- 涉及 SEO 的功能应同时考虑静态生成、SSR 与 Docker 部署。
- 涉及微信分享的功能应同时验证公众号后台配置、域名白名单、CSP 与反向代理。
- 涉及主题的功能应确认设置状态、CSS 变量和实际组件渲染三者都已接通。
- 涉及 AI/LLM 的功能应区分“打开外部 AI 页面”和“接入模型 API”，当前项目只实现了前者以及
nuxt-llms内容入口。