产品简介与核心价值
EpoCanvas Docs 是专门为 EpoCanvas 开源生态打造的官方技术文档站点系统。它基于现代静态网站框架 Astro 5 和 Starlight 构建，旨在为开发者提供一个排版专业、打开快、搜索顺手、易于维护的文档平台。
无论是编写产品的用户手册、API 接口规范，还是记录系统架构设计，EpoCanvas Docs 都能让撰写者专注于写好 Markdown 内容，同时为阅读者提供舒适自然的浏览体验。
解决的实际问题
在日常开发和技术写作中，许多团队在维护文档时常遇到以下困扰：
- 页面打开慢、占用内存高：很多文档工具生成的页面带有大量 JavaScript 运行时，手机或弱网环境下打开慢，滚动长文章时容易卡顿。
- 长文章导航费劲：常见文档站通常只有左侧菜单，阅读数千字的长篇技术说明时，难以快速了解当前文章内部的小标题层级。
- 搜索依赖外部服务：常见的 Algolia 等云端搜索服务需要额外申请账号、配置爬虫密钥，在无法访问外部服务的内网环境中完全失效。
- 多语言只有半套：不少文档站宣称支持多语言，实际只有导航按钮翻译了，点进文章正文还是原文；也有的译文缺失时直接 404，读者只能自己改 URL 找内容。
EpoCanvas Docs 正是为了解决这些实际痛点而设计的。
核心功能一览
图：产品简介页的实际渲染效果。左侧为文档分类目录，中央为正文，右侧为自动生成的”本页目录”大纲，随滚动高亮当前小节。
1. 清晰的三栏式阅读界面
- 左侧导航栏：按模块组织所有文档分类，带有层级折叠，换页不跳动。
- 中央正文区：正文最大宽度 60rem，行距 1.68，代码块自适应宽度，长时间阅读不易疲劳。
- 右侧大纲栏：自动抓取文章内的
h2和h3标题生成”本页目录”，随滚动高亮当前阅读位置，点击任意小标题平滑跳转。
2. 双模式搜索：页内查找 + 全站检索
- 当前页查找：直接在顶部搜索框输入关键词，页面内所有匹配文字立即高亮，并显示
3/9这样的进度计数，按回车逐个跳转。 - 全站检索弹窗：按下
Ctrl + K（Mac 为Cmd + K）打开全局检索弹窗，基于 Pagefind 静态索引列出所有命中的文档和段落预览。 - 全部搜索能力都在浏览器本地完成，不依赖任何后端服务，托管在内网也能用。
3. 10 种语言的完整译文
- 支持简体中文、繁体中文、英语、日语、韩语、西班牙语、法语、德语、俄语、葡萄牙语共 10 种语言，每种语言的导航、侧边栏与全部文档正文都是完整翻译。
- 点击右上角语言按钮即可跳转到同一篇文章的目标语言版本，URL 带语言前缀（如
/en/canvas/），可直接收藏或分享给使用其他语言的同事。 - 个别页面暂缺某语言译文时，该页自动回退显示默认中文内容，不会出现 404 报错。
4. 专业的 Markdown 与代码排版
- 基于 Expressive Code 的代码高亮，支持为代码块标注文件名标题、高亮指定行、展示 diff 对比。
- 原生支持 4 种彩色提示框（Note、Tip、Caution、Danger），并支持自定义标题。
- 支持 GFM 表格、任务清单、删除线等常用 Markdown 扩展语法，完整规则见渲染规则详解。
5. 构建快、托管免费
- 基于 Astro 5 静态编译，构建产物为纯 HTML、CSS 与少量按需加载的 JS，全站 10 种语言约 180 个页面完整构建约 25 秒。
- 预置 Cloudflare Pages 部署命令，一行指令即可将文档发布到线上，并自动获得 HTTPS 证书。
项目整体架构
为了让文档保持轻巧好维护，系统按职责划分为四个部分：
图：系统架构。撰写者只需维护 Markdown 内容源，其余环节全部自动完成。
- 底座与样式：基于 Astro 5 静态内核，通过
src/styles/custom.css定义设计变量，浅色与深色模式共用同一套变量名。 - 内容源管理：所有文档保存在
src/content/docs/目录下，使用纯 Markdown（.md）或可嵌入组件的 MDX（.mdx）撰写。 - 界面组件：通过覆盖 Starlight 原生组件，定制了顶栏、侧边栏、本页目录与搜索弹窗。
- 分发与访问：编译产物保存在
dist/目录，托管在 Cloudflare Pages，由全球 CDN 节点就近响应。
适合谁用
EpoCanvas Docs 适合以下场景：
- 开源项目的官方文档站：产品手册、API 参考、架构说明，一个仓库全部搞定；
- 团队内部知识库：纯静态、无外部服务依赖，放在内网也能完整使用搜索；
- 个人技术博客式文档：只写 Markdown，不操心前端工程，一条命令发布。
它不适合需要登录鉴权、评论互动、实时数据展示的场景——纯静态站点没有后端，这类需求需要另行搭配服务。
常用文档工具对比
| 功能特性 | EpoCanvas Docs | Docusaurus | VitePress | GitBook 商业版 |
|---|---|---|---|---|
| 底层技术 | Astro 5 + Starlight | React 18 | Vue 3 + Vite | 闭源 SaaS 平台 |
| 搜索机制 | Pagefind 本地静态索引 | 依赖 Algolia 云服务 | Minisearch 内存搜索 | 自带后端检索 |
| 布局设计 | 三栏（左菜单 + 中正文 + 右目录） | 需要配置插件改造 | 默认双栏/三栏 | 固定两栏 |
| 部署方式 | Cloudflare Pages 直传 | S3 / Vercel / GitHub | GitHub Pages | 平台私有托管 |
| 自主可控度 | 100% 开源，源码完全在手 | 100% 开源 | 100% 开源 | 闭源，收费功能多 |
技术栈与版本
当前版本实际使用的技术栈（以构建产物为准）：
| 组件 | 版本 | 作用 |
|---|---|---|
| Astro | v5.18.2 | 静态站点内核，负责构建与路由 |
| Starlight | v0.32.6 | 文档站框架，提供布局骨架与内容处理 |
| Expressive Code | 随 Starlight 集成 | 代码块高亮、标题栏、行高亮 |
| Pagefind | 经 @pagefind/default-ui 1.5.2 集成 | 构建期生成静态搜索索引 |
| Wrangler | v4.131.0 | Cloudflare 官方 CLI，执行部署 |
| 运行环境 | Node.js 18.20.8 / 20.3+ / 22+，pnpm 10 | 本地开发与构建环境；执行 pnpm run deploy 时 wrangler 要求 Node.js 22 及以上 |
升级依赖时请同步阅读 界面组件与二次开发 中的回归测试注意事项。
项目目录结构
本项目的代码组织如下，各目录分工明确：
epocanvas-docs/├── public/ # 静态资源目录（图片、矢量图标直接放这里）│ └── images/canvas/ # 界面截图与系统架构矢量图├── src/│ ├── components/starlight/ # 定制的页面组件（顶栏、侧边栏、本页目录、搜索弹窗等）│ ├── config/navigation.ts # 顶部导航栏配置（增删菜单项改这里）│ ├── content/docs/ # 文档正文 Markdown 文件存放位置│ │ ├── index.mdx # 文档站首页落地页│ │ ├── canvas/ # 各章节文档（简体中文，默认语言）│ │ └── en/ ja/ ... # 其他 9 种语言的完整译文目录│ ├── styles/custom.css # 全局样式与主题颜色变量│ ├── utils/i18n.ts # 界面词条字典与语言清单│ └── pages/404.astro # 自定义 404 页（按浏览器语言输出提示文案）├── scripts/ # 构建前缓存失效、i18n/图片/锚点校验与截图脚本├── astro.config.mjs # 站点主配置文件（标题、语言列表、侧边栏目录在这里配）└── package.json # 项目依赖与运行命令配置下一步
- 想在本地把项目跑起来？请阅读 快速上手 (3分钟运行)。
- 想了解界面的具体布局与使用方式？请阅读 页面布局与阅读体验。
- 想开始撰写新文档？请阅读 Markdown 编写与排版指南 与 渲染规则详解。