docs(contributing): 按现状改写文档目录说明,站点源是 content/docs/ (#3584)

[yinlianghui]

Fixes#3584

### Writing Documentation 开头那句「We use fumadocs for documentation. All docs are in docs/.」停在搬迁前。它恰好是新贡献者「文档该写在哪」的第一落点 —— 照它做的人会把新页面放进根 docs/,站点上永远不出现。

前提复核(先在分支点上验,再动手)

四条只读命令全中,与单里一致:

grep -n 'All docs are in' CONTRIBUTING.md => 414:We use fumadocs for documentation. All docs are in `docs/`.
apps/site/source.config.ts:6 => dir: '../../content/docs'
ls docs/ => ARCHITECTURE.md CONSOLE-STREAMLINING-SUMMARY.md adr audits screenshots
ls content/docs/ => api blocks components core fields guide index.md layout meta.json plugins rfcs utilities

分支点 39477b03b(含 #3585、#3571 对本文件的改动)。

改动

一句改两句,按机制不按枚举:

• 站点页面在 content/docs/**,该根只声明一处 —— apps/site/source.config.ts 的 dir: '../../content/docs',文件在该根下的路径即其 /docs 路由;
• 仓库根 docs/不属于站点:放 ADR / 审计 / 架构笔记等内部材料,fumadocs 的 collection 根本不读它,因此不渲染、也没有 /docs/... 路由。

baseUrl: '/docs' 的机制说明没有重复写 —— 同节稍后的 #### Why? 已经拥有那段(锚点 apps/site/lib/source.ts:7),这里只用一句把「路径即路由」接上去。

刻意没写的一句

单的正文提到「链接门禁也不看那棵树(SCAN_ROOTS 里没有它)」。这句没有写进文档:#3572 / PR #3589 正要把 docs 加进 SCAN_ROOTS,那条断言落地当天就会变假 —— 正是本单要修的那种「枚举式陈述随实现漂移」。同节「Validating Links」已经写了 read them there instead of trusting a list copied into prose,本次沿用同一种「指向声明处」的写法。

与 #3585 的连贯性(读全节后确认)

同节其余段落无冲突,且互相接得上:#### ❌ Incorrect Link Patterns 已用「top-level section that does not exist under content/docs/」,#### Why? 的 baseUrl: '/docs',以及 #3585 刚改写的门禁分工段 —— 三处都以 content/docs/ 为前提,此前唯独开头这句还停在 docs/。

围栏两行注释

顺带把紧随的围栏注释由 # Start docs dev server / # Build docs 改为 # Start the documentation site dev server / # Build the documentation site,以免与新段落里刚区分开的根 docs/ 混读。属「该句 ± 最小相邻散文」,如实披露。

两条命令经核实有效(单里要求的顺带确认):根 package.json 有 site:dev = pnpm --filter @object-ui/site dev、site:build = pnpm --filter @object-ui/site build,均未改。

验证(先定方向,再跑)

检查	预告	实际
node scripts/check-doc-links.mjs	exit 0 —— 本改动零新增 markdown 链接,且分支点上 CONTRIBUTING.md 不在 SCAN_ROOTS 内,结构上无从影响	✅ Links are valid across 3 scan roots. exit 0
node scripts/check-control-bytes.mjs	OK	✅ OK (scanned 3637 tracked text file(s); skipped 85 binary)
pnpm exec vitest run scripts/ --maxWorkers=2	保持绿,数字不变(未碰任何脚本)	✅ 16 passed (16) / 275 passed (275)
grep -naP 控制字符自扫(超出门禁扫描面)	clean	✅ clean

扫描面状态,如实记录

跑测时 PR #3589 尚未合并(Links are valid across **3** scan roots 即证据 —— content/docs / examples / README.md),所以 CONTRIBUTING.md不在门禁扫描面内,上面那条 exit 0 并未真正校验本文件的链接。

为了不把「空绿」当成证据,另做了一次预览:在 scratchpad 里 import 该脚本导出的 SCAN_ROOTS(可变数组)与 collectBrokenLinks,push 一行 { path: 'CONTRIBUTING.md', rule: 'disk' } 后重跑,未改任何被跟踪文件:

total broken across 4 roots: 0
broken in CONTRIBUTING.md: 0

即 #3589 落地后本文件依旧干净。另需说明:本改动新增的散文里没有任何 markdown 链接,只有行内代码;而 stripCode() 会在扫描前抹掉行内代码 —— 所以即便扫描面覆盖到,这两段对该门禁也基本不可见。这是散文事实断言的通病,也正是本单「没有任何检查会因为这句话变假而变红」的由来。

无 changeset:根目录文档,非用户可见的包变更。未触碰 content/docs/releases/。

顺手发现(未在本 PR 修,已另立单)

#3596(未认领、未打标,留 PM 分诊):把「确认命令仍有效」这一步推到全文后发现,CONTRIBUTING.md:84-91 的 ### Running Development Servers 三条命令 —— pnpm designer / pnpm prototype / pnpm docs:dev —— 在根 package.json 里一个都不存在,是新贡献者第一批照抄的命令。其中 docs:dev 与本单同源(docs: 前缀站点脚本已改名到 site:)。该处在 PM 认领评论锁定的文件面之外,按 Prime Directive #10 未在本 PR 修。

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 7, 2026 3:09pm