From 36ceae6c5ccce42cad49e0b164628b610fae4e44 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 7 Aug 2026 15:07:11 +0000 Subject: [PATCH] =?UTF-8?q?docs(contributing):=20=E6=8C=89=E7=8E=B0?= =?UTF-8?q?=E7=8A=B6=E6=94=B9=E5=86=99=E6=96=87=E6=A1=A3=E7=9B=AE=E5=BD=95?= =?UTF-8?q?=E8=AF=B4=E6=98=8E,=E7=AB=99=E7=82=B9=E6=BA=90=E6=98=AF=20conte?= =?UTF-8?q?nt/docs/=20(#3584)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `### Writing Documentation` 开头的「All docs are in `docs/`」停在搬迁前,而它 正是新贡献者「文档写在哪」的第一落点 —— 照它做的人会把新页面放进根 `docs/`, 站点上永远不出现。 改写为两句,按机制不按枚举: - 站点页面在 `content/docs/**`,该根**只声明一处** —— `apps/site/source.config.ts` 的 `dir: '../../content/docs'`,文件在该根下的 路径即其 `/docs` 路由; - 仓库根 `docs/` **不属于站点**:放 ADR / 审计 / 架构笔记等内部材料,fumadocs 的 collection 根本不读它,因此不渲染、也没有 `/docs/...` 路由。 刻意**不写**「链接门禁不扫 `docs/`」一类的枚举式断言 —— #3572 / PR #3589 正要 把 `docs` 加进 `SCAN_ROOTS`,那句话落地当天就会变假。同节「Validating Links」 已经写了「read them there instead of trusting a list copied into prose」,本次 沿用同一种「指向声明处」的写法,与 #3585 刚改写的门禁分工段一致。 顺带把紧随的围栏两行注释由「docs」改为「documentation site」,以免与新段落里 刚刚区分开的根 `docs/` 混读。两条命令 `pnpm site:dev` / `pnpm site:build` 经核 实在根 package.json 中存在,未改。 Fixes #3584 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01GTRjn8xBqp75dk7kFupVRt --- CONTRIBUTING.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e72bfcb17a..d10422e57e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -411,13 +411,15 @@ These thresholds are intentionally set just below current coverage levels to pre ### Writing Documentation -We use fumadocs for documentation. All docs are in `docs/`. +We use fumadocs for documentation. The published pages live in `content/docs/**` — that root is declared once, in `apps/site/source.config.ts` (`dir: '../../content/docs'`) — and a file's path below it becomes its route under `/docs`. New and updated documentation pages go there. + +The repository root also has a `docs/` directory, and it is **not** part of the site: it holds internal engineering material (ADRs, audits, architecture notes) that the fumadocs collection never reads, so none of it is rendered or reachable at a `/docs/...` route. A page filed there never reaches the site. ```bash -# Start docs dev server +# Start the documentation site dev server pnpm site:dev -# Build docs +# Build the documentation site pnpm site:build ```