From 3405dcf5b9d23e43f69a0d2f19e00d54649ecc22 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 26 Jul 2026 03:13:19 +0000 Subject: [PATCH] =?UTF-8?q?fix(docs):=20=E7=9B=B8=E5=AF=B9=E9=93=BE?= =?UTF-8?q?=E6=8E=A5=E4=B8=8D=E5=BE=97=E9=80=83=E5=87=BA=20docs=5Fdir?= =?UTF-8?q?=EF=BC=88OCP=20=E5=A5=91=E7=BA=A6=EF=BC=89?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 将 ./docs/ 前缀特判升级为解析后必须落在 docs/ 内的单一规则， 并把 13 处 ../../仓内路径 改为 GitHub 绝对 URL，避免 Pages 404。 Co-authored-by: Shiroha --- docs/CONTRIBUTING-DOCS.md | 6 ++++++ docs/dev/npm-publish.md | 8 ++++---- docs/guide/config.md | 2 +- docs/guide/pack-update.md | 16 ++++++++-------- tools/docs-mkdocs.mjs | 40 +++++++++++++++++++++++++++------------ 5 files changed, 47 insertions(+), 25 deletions(-) diff --git a/docs/CONTRIBUTING-DOCS.md b/docs/CONTRIBUTING-DOCS.md index a469fe0..57c897c 100644 --- a/docs/CONTRIBUTING-DOCS.md +++ b/docs/CONTRIBUTING-DOCS.md @@ -54,6 +54,12 @@ npm run docs:build # TypeDoc + mkdocs build → site/ 2. 写入该目录 `.pages` 的 `nav` 列表 3. 从章节 `index.md` 加链接 +### 链接约定（契约） + +- **站内页**：用相对 `docs/` 的路径（`./guide/`、`../dev/`），**不要**写成仓根的 `./docs/...`。 +- **仓外目标**（源码、workflow、LICENSE、`configs/` 等）：用 GitHub 绝对 URL（`https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/...`）。相对 `../../sfmc/...` 在 Pages 上会 404。 +- `npm run docs:build` / `docs:serve` 会解析手写 `.md` 相对链接；逃出 `docs/` 即失败。 + ## 扩展 TypeDoc 入口 在根目录 `typedoc.json` 的 `entryPoints` 追加 SDK 公开入口（与 `package.json#exports` 对齐）。 diff --git a/docs/dev/npm-publish.md b/docs/dev/npm-publish.md index 23f18f4..2e58a29 100644 --- a/docs/dev/npm-publish.md +++ b/docs/dev/npm-publish.md @@ -19,7 +19,7 @@ | `@sfmc-bds/tools` | `tools/` | 开发/安装工具脚本 | | `@sfmc-bds/sfmc` | `sfmc-meta/` | **聚合包**：一条命令装齐平台 | -可发包清单权威来源：[`tools/lib/npm-publish-packages.mjs`](../../tools/lib/npm-publish-packages.mjs)。 +可发包清单权威来源：[`tools/lib/npm-publish-packages.mjs`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/tools/lib/npm-publish-packages.mjs)。 `@sfmc-bds/remote-controller` 为内部实验包，**不发布**（已在 `.changeset/config.json#ignore`）。 @@ -36,7 +36,7 @@ ## 日常开发流程 1. 改可发包代码后：`npm run changeset`，选包 + type，写中文摘要。 -2. PR 合入 `main` 后，[changeset-release.yml](../../.github/workflows/changeset-release.yml) 会开/更新 **Version Packages** PR。 +2. PR 合入 `main` 后，[changeset-release.yml](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/.github/workflows/changeset-release.yml) 会开/更新 **Version Packages** PR。 3. 维护者审查并合并 Version PR → CI 跑 `ci-release-packages`（publish + tag + GitHub Release；pre mode → npm **`beta`**）。 ### Version PR 权限（必读） @@ -73,7 +73,7 @@ npm run prerelease-packages ## Beta-only（硬约束） -- 仓库含 [`.changeset/pre.json`](../../.changeset/pre.json)：`mode: pre`, `tag: beta`。 +- 仓库含 [`.changeset/pre.json`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/.changeset/pre.json)：`mode: pre`, `tag: beta`。 - 安装文档与脚手架一律写 `@beta`。 - 已存在的 `latest` 上的 `0.1.0` **保留不动**；稳定通道未开放。 - **退出 beta → latest 门槛（全部满足才 `changeset pre exit`）**： @@ -92,7 +92,7 @@ npx changeset publish # → latest ## 应急单包补发 -[npm-publish.yml](../../.github/workflows/npm-publish.yml) 仅 `workflow_dispatch`： +[npm-publish.yml](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/.github/workflows/npm-publish.yml) 仅 `workflow_dispatch`： - 默认 `dist_tag=beta` - 若仍处于 pre mode，选择 `latest` 会被 workflow 拒绝 diff --git a/docs/guide/config.md b/docs/guide/config.md index 0be4f57..885a93b 100644 --- a/docs/guide/config.md +++ b/docs/guide/config.md @@ -2,7 +2,7 @@ 首次启动时，**各服务用代码内默认值 ensure 生成**缺失配置文件，并写入 `$schema` ，使用 IDE 时便可查看**详细的悬停说明**。 -> IDE：工作区 [`.vscode/settings.json`](../../.vscode/settings.json) 已按文件名绑定 schema；也可用文件内 `$schema` 指向 `@sfmc-bds/sdk/schemas/*.schema.json`。 +> IDE：工作区 [`.vscode/settings.json`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/.vscode/settings.json) 已按文件名绑定 schema；也可用文件内 `$schema` 指向 `@sfmc-bds/sdk/schemas/*.schema.json`。 ## 平台配置 diff --git a/docs/guide/pack-update.md b/docs/guide/pack-update.md index 802b1bc..6fa7e5a 100644 --- a/docs/guide/pack-update.md +++ b/docs/guide/pack-update.md @@ -6,12 +6,12 @@ | 路径 | 职责 | |------|------| -| [`sfmc/src/pack-update/`](../../sfmc/src/pack-update/) | 配置、绑定、CF Provider、探测/检查/应用 | -| [`sfmc/src/world-packs.ts`](../../sfmc/src/world-packs.ts) | CLI 接线、安装后探测钩子 | -| [`sfmc/src/services.ts`](../../sfmc/src/services.ts) | BDS `beforeStart` 检查/应用 | -| [`bds-tools/src/world-packs.ts`](../../bds-tools/src/world-packs.ts) | 安装/enable/抬版权威实现 | -| [`modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts`](../../modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts) | 进度条与日志共存 | -| [`configs/pack-update.json`](../../configs/pack-update.json) | 运行时配置（首次由 sfmc ensure 写入内置 DEFAULTS） | +| [`sfmc/src/pack-update/`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/tree/main/sfmc/src/pack-update) | 配置、绑定、CF Provider、探测/检查/应用 | +| [`sfmc/src/world-packs.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/world-packs.ts) | CLI 接线、安装后探测钩子 | +| [`sfmc/src/services.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/services.ts) | BDS `beforeStart` 检查/应用 | +| [`bds-tools/src/world-packs.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/bds-tools/src/world-packs.ts) | 安装/enable/抬版权威实现 | +| [`modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/modules/sdk/@sfmc-sdk/src/logs/terminal-progress.ts) | 进度条与日志共存 | +| `configs/pack-update.json` | 运行时配置（gitignore；首次由 sfmc ensure 写入内置 DEFAULTS，见 [`config.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/pack-update/config.ts)） | 通用收件箱安装见 [资源包管理](./world-packs.md)。 @@ -71,7 +71,7 @@ flowchart TD 不再从 `configs-default` 拷贝。`createServices()` / `ensurePackUpdateConfigFile()` 在文件缺失时写入代码内 `DEFAULTS`，并附带 `$schema`（见 `@sfmc-bds/sdk/schemas/pack_update.schema.json`）。 -权威实现：[`sfmc/src/pack-update/config.ts`](../../sfmc/src/pack-update/config.ts) 的 `ensurePackUpdateConfigFile`。 +权威实现：[`sfmc/src/pack-update/config.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/pack-update/config.ts) 的 `ensurePackUpdateConfigFile`。 ### 3.3 `pack-update.json` 关键字段 @@ -189,7 +189,7 @@ JSON 中 `$` **无需**加倍；仅当把 key 放进 **shell / docker-compose | `GET /v1/mods/search?...` | **部分 key 恒 403**（`Forbidden: API Key missing or invalid`） | | `GET https://api.curse.tools/v1/cf/mods/search?...` | 200（社区镜像，路径约定与官方类似） | -实现策略（[`providers/curseforge.ts`](../../sfmc/src/pack-update/providers/curseforge.ts)）： +实现策略（[`providers/curseforge.ts`](https://github.com/DogeLakeDev/ScriptsForMinecraftServer/blob/main/sfmc/src/pack-update/providers/curseforge.ts)）： 1. 先打官方 `baseUrl` + `/v1/mods/search`。 2. 若返回 403 → 静默改打 `searchBaseUrl`（默认 `https://api.curse.tools/v1/cf`）的 `/mods/search`。 diff --git a/tools/docs-mkdocs.mjs b/tools/docs-mkdocs.mjs index fa249fa..64d9a11 100644 --- a/tools/docs-mkdocs.mjs +++ b/tools/docs-mkdocs.mjs @@ -18,44 +18,60 @@ if (!["serve", "build"].includes(mode)) { } /** - * MkDocs docs_dir=docs：页面内相对链接不应再带 ./docs/ 前缀。 - * 把 README（仓根路径）原样贴进 docs/*.md 会导致站内导航全断，且默认 - * unrecognized_links=ignore 时 CI 不会拦。在此做契约检查。 + * MkDocs docs_dir=docs：手写页相对链接解析后必须落在 docs/ 内。 + * 同时拦住两类误用（单一权威规则，避免再为每种前缀打洞）： + * 1) README 仓根路径误贴：](./docs/guide/…) → 站内变成双重 docs/ + * 2) 指向仓内其它目录：](../../sfmc/…) → Pages 上 404；应改 GitHub 绝对 URL + * TypeDoc 生成目录跳过；mkdocs exclude（plan/archive/reviews）仍检查，防草稿误贴。 */ -function assertNoRepoRootDocsLinks(docsDir) { +function assertDocsRelativeLinksStayInDocs(docsDir) { const bad = []; + const linkRe = /\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g; const stack = [docsDir]; while (stack.length) { const dir = stack.pop(); for (const ent of readdirSync(dir, { withFileTypes: true })) { const full = path.join(dir, ent.name); if (ent.isDirectory()) { - // TypeDoc 输出目录跳过；plan/archive 由 mkdocs exclude const rel = path.relative(docsDir, full).replace(/\\/g, "/"); - if (rel === "reference/sdk" || ent.name === "plan" || ent.name === "archive") continue; + // 仅跳过 TypeDoc 输出（生成物，非手写契约） + if (rel === "reference/sdk") continue; stack.push(full); continue; } if (!ent.name.endsWith(".md")) continue; const text = readFileSync(full, "utf8"); - // Markdown 链接目标：](./docs/...) 或 ](docs/...) - if (/\]\(\.?\/?docs\//.test(text)) { - bad.push(path.relative(root, full)); + const fileRel = path.relative(root, full).replace(/\\/g, "/"); + let m; + linkRe.lastIndex = 0; + while ((m = linkRe.exec(text))) { + const raw = m[1].replace(/^<|>$/g, ""); + // 锚点 / 协议链接 / 协议相对 URL 不参与 docs_dir 解析 + if (!raw || raw.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(raw) || raw.startsWith("//")) { + continue; + } + const targetPath = raw.split("#")[0].split("?")[0]; + if (!targetPath) continue; + const resolved = path.resolve(path.dirname(full), targetPath); + const relToDocs = path.relative(docsDir, resolved); + if (relToDocs.startsWith("..") || path.isAbsolute(relToDocs)) { + bad.push(`${fileRel}: ](${raw})`); + } } } } if (bad.length) { console.error( [ - "[docs-mkdocs] 发现仓根相对路径 docs/…（MkDocs 下应写成 ./guide/、./dev/ 等）：", - ...bad.map((f) => ` - ${f}`), + "[docs-mkdocs] 相对链接逃出 docs/（站内应写 ./guide/ 等；仓外目标用 GitHub 绝对 URL）：", + ...bad.map((line) => ` - ${line}`), ].join("\n") ); process.exit(1); } } -assertNoRepoRootDocsLinks(path.join(root, "docs")); +assertDocsRelativeLinksStayInDocs(path.join(root, "docs")); // 先生成 API 文档 const gen = spawnSync(process.execPath, [path.join(root, "tools", "docs-typedoc.mjs")], {