82 lines
4.4 KiB
Markdown
82 lines
4.4 KiB
Markdown
# Felis 文档站
|
||
|
||
基于 VitePress 默认主题，使用 Felis 黄绿色配色。参考 [Vdrias World Manual](https://github.com/vdriasworld/manual) 的插件选型，接入 Nólëbase 阅读增强与标题定位；使用 Mermaid 渲染主仓库的时序图。导航、搜索、代码复制和主题切换由 VitePress 提供。
|
||
|
||
## 本地开发
|
||
|
||
需要 Node.js 22+ 与 Bun 1.3.14。
|
||
|
||
```sh
|
||
bun install --frozen-lockfile
|
||
bun run docs:dev
|
||
```
|
||
|
||
```sh
|
||
bun run docs:build
|
||
bun run docs:preview
|
||
```
|
||
|
||
文档放在 `docs/`，导航与侧栏在 `docs/.vitepress/config.mts`，品牌色与样式在 `docs/.vitepress/theme/style.css`。入口直接显示带侧栏的文档正文，沿用 VitePress 默认主题。
|
||
|
||
## 中英文内容
|
||
|
||
仅提供简体中文与英文。中文页面沿用 `docs/` 下的现有路径，英文对应页面放在 `docs/en/`，例如 `docs/guide/deployment.md` 对应 `docs/en/guide/deployment.md`。VitePress 的语言菜单切换到同一篇文章，导航、侧栏、搜索与阅读增强菜单随语言切换。搜索索引按语言划分。
|
||
|
||
修改技术内容时同时更新两种语言，命令、配置键、错误码和验证标记保持一致。标题末尾的 `{#章节标识}` 在对应页面中使用同一值；翻译标题时保留该标识，避免旧链接和语言切换后的章节定位失效。OpenAPI、许可证和图片由两种语言共用 `docs/public/` 下的原件。
|
||
|
||
## 发布
|
||
|
||
使用 Bun 安装依赖和执行 VitePress 构建，产物目录为 `docs/.vitepress/dist`。
|
||
|
||
### Cloudflare Pages
|
||
|
||
连接本仓库后，填写以下构建设置：
|
||
|
||
| 设置 | 值 |
|
||
| --- | --- |
|
||
| 框架预设 | `VitePress`，随后覆盖下面的命令和输出目录 |
|
||
| 根目录 | 留空（仓库根目录） |
|
||
| 构建命令 | `bun install --frozen-lockfile && bun run docs:build` |
|
||
| 构建输出目录 | `docs/.vitepress/dist` |
|
||
|
||
生产环境和预览环境都添加以下环境变量：
|
||
|
||
| 变量 | 值 |
|
||
| --- | --- |
|
||
| `BUN_VERSION` | `1.3.14` |
|
||
| `NODE_VERSION` | `22` |
|
||
| `SKIP_DEPENDENCY_INSTALL` | `1` |
|
||
|
||
构建命令按 `bun.lock` 显式安装依赖，因此关闭 Pages 的自动依赖安装。`pages.dev` 或独立文档域名使用默认的 `/`，无需设置 `DOCS_BASE`。版本变量与跳过自动安装的设置参见 [Cloudflare 构建环境文档](https://developers.cloudflare.com/pages/configuration/build-image/)。
|
||
|
||
### 部署到子路径
|
||
|
||
如果使用 `https://felismc.github.io/docs/`，构建时设置 `DOCS_BASE=/docs/`：
|
||
|
||
```sh
|
||
DOCS_BASE=/docs/ bun run docs:build
|
||
```
|
||
|
||
## 内容来源
|
||
|
||
内容以 [Felis 主仓库](https://github.com/FelisMC/Felis) 为准，本次迁移基于本地提交 `2e4f118939aec47852c181f8043f8ab98c62014c`。两种语言保留原文的命令、限制与验证标记。入门内容分别使用 `README.md`、`README_EN.md`；技术文章的译文与对应原文保持相同结构和章节标识。
|
||
|
||
| 主仓库来源 | 文档站位置 |
|
||
| --- | --- |
|
||
| `README.md` | 认识 Felis、安装与部署、管理服务器、备份与恢复、从源码构建、开源协议 |
|
||
| `docs/operations.md` | `docs/operations/index.md` |
|
||
| `docs/troubleshooting.md` | `docs/operations/troubleshooting.md` |
|
||
| `docs/distributed.md` | `docs/guide/distributed.md` |
|
||
| `docs/sequence-diagrams.md` | `docs/reference/sequence-diagrams.md` |
|
||
| `docs/deferred-seams.md` | `docs/reference/deferred-seams.md` |
|
||
| `CONTRIBUTING.md` | `docs/reference/contributing.md` |
|
||
| `plugins/README.md` | `docs/reference/plugins.md` |
|
||
| `deploy/lobby/README.md`、`deploy/limbo/README.md` | `docs/reference/lobby.md`、`docs/reference/limbo.md` |
|
||
| `README.md`、`README_EN.md` | 中英文的 `reference/readme-en.md`（项目说明，保留原有地址） |
|
||
| `docs/openapi.yaml` | `docs/public/openapi.yaml`，由 API 定义页面提供下载 |
|
||
| `LICENSE` | `docs/public/LICENSE.txt` |
|
||
|
||
部署架构及入门页面摘取上述原文，并链接到完整手册。更新功能说明时先核对主仓库对应文章，保留其发布通道、实验性状态与验证边界，避免独立改写出另一套口径。每页末尾均链接到主仓库原文。
|
||
|
||
渲染适配：故障排查里跨行的行内代码已合并一处换行；时序图的文本分号使用 [Mermaid 要求的 `#59;` 转义](https://mermaid.js.org/syntax/sequenceDiagram.html#entity-codes-to-escape-characters)；数字开头的章节锚点按 VitePress 的格式添加 `_`，两种语言通过显式章节标识共享锚点。README 的居中品牌页眉改为普通 Markdown。
|