Repository navigation
[finding] 1316 duplicate heading anchors remain on 162 of 214 reference pages — the section grammar's own headings (### Properties, ### Allowed Values, #### Option N) carry no qualifier at all #12862
Description
Observation recorded while fixing #12590 (duplicate ### Nested Shape: anchors). Filing rather than fixing: it is a much larger population with a different decision behind it, and #12590's card explicitly scoped itself to the per-key qualified headings.
What was measured
Counting duplicate heading TEXTS per emitted page under content/docs/references/**, on the tree regenerated with #12590's fix applied (214 pages):
excess=1316 pages=162 distinct heading texts=6
Broken down by heading text (excess occurrences summed across pages):
| excess | heading |
|---|---|
| 1133 | ### Properties |
| 145 | ### Allowed Values |
| 12 | ### Union Options |
| 12 | #### Option 1 |
| 12 | #### Option 2 |
| 2 | #### Option 3 |
The worst single page is content/docs/references/ui/view.mdx with 44 occurrences of ### Properties; api/protocol.mdx has 124.
Why this is a separate question from #12590
Two different kinds of heading live on these pages, and only one of them was ever qualified:
- Per-key headings —
### Nested Shape: \Schema.key`and### Allowed Values: `Schema.key`. These exist to be uniquely addressable; theSchema.key` qualifier is there precisely so one page cannot mint the same anchor twice. [finding] 12 duplicate### Nested Shape:anchors on 4 reference pages — a union-variant table qualifies its heading by schema+key, and sibling variants share both #12590 fixed the case where two sibling union variants shared both halves of that qualifier (12 excess / 4 pages), and the qualified population is now zero. - Section-grammar headings —
### Properties,### Allowed Values,### Union Options,#### Option N. These are structural labels emitted once per schema section (or once per union variant), and they carry no qualifier by construction. One page carries many schema sections, so they repeat by design.
So this is not the same defect one level up; it is the open question of whether the section grammar should be addressable at all.
What is NOT claimed here
- Nothing in the repo is known to link to these anchors.
check:doc-anchorschecks that links resolve, never that anchors are unique, and it is green. - Whether the docs site's slugger de-duplicates repeated headings (appending
-1,-2) was not measured. If it does, the harm is a reader/AI-author addressing problem rather than a broken link, and the counts above are still the honest measure of how many headings are not independently addressable.
Triage should decide between: qualify the section grammar the way the per-key headings are qualified; demote these to a non-heading rendering so they mint no anchor; or accept them and say so in the renderer so the next reader of the Schema.key qualifier does not read the inconsistency as a bug.
Reproduce with any per-file duplicate-heading count over content/docs/references/**, e.g. counting identical lines matching ^#{1,6}\s within each page and summing count - 1.
Activity
huangyiirene commentedon Aug 28, 2026
定级:
Task·documentation·domain:spec·pm:queue—— 但范围是那条未测量的事实,⛔ 不是三选一分诊座位,session
session_01Aujz2zykf5LXt3T98gRsGe。⛔ 我不在三个选项里挑,理由是卡自己写的
卡请分诊在「qualify / demote / accept」之间裁。在这一轮我拒绝裁,因为卡自己诚实标注了一条会改变答案的空白:
⇒ 这一条把三个选项分成两个完全不同的世界:
-1/-2)### Properties争一个 id,链接可以静默指到错的那一节⛔ 在这条测量之前选任何一个都是猜。而这张卡的整个价值就在于它把数量测准了(
excess=1316 / pages=162 / distinct=6,最坏单页api/protocol.mdx124 次)—— 在一个测准的数量上叠一个没测的机制,会把精确变成误导。范围钉死:只做测量 + 上报,⛔ 不动渲染器
⭐ 卡里最该被读到的一句
⇒ 它正确地拒绝了「和 #12590 是同一个缺陷」这个诱人的读法。per-key 标题(
### Nested Shape: \Schema.key`)带限定符**正是为了唯一可寻址**;**section-grammar 标题**(### Properties` 等)按构造就没有限定符,一页多个 schema section 时按设计重复。⇒ #12590 修的是限定符失效,本卡问的是「这一类本来该不该有限定符」。⛔ 不要把本卡当成 #12590 的续集去做。采信与保留
### Nested Shape:anchors on 4 reference pages — a union-variant table qualifies its heading by schema+key, and sibling variants share both #12590 修复后重新生成的树上测的(214 页),口径干净。check:doc-anchors只检查链接可解析、从不检查锚点唯一 —— 这解释了为什么它今天全绿而问题存在,是一条有价值的仪器读数。相关
#12590(
pm:dispatched·domain:spec,per-key 那一半)Generated by Claude Code
huangyiirene commentedon Aug 29, 2026
重新定级（
pm:retriage已摘）：范围 = accept + 在渲染器里写明，pm:queue·domain:spec·documentation·priority:p2这是本席 8-28 定级时预登记的返回路径（「拿到读数后回来重新定级」，评论 5449394657）。⛔ 不是纠错、不是反对 —— 机制按设计走完了一圈。
读数落进我自己预登记的哪一行
当时那张表把三个选项劈成两个世界：
实测答案是去重，而且是在站点真实编译路径上驱动出来的（
fumadocs-mdx/noderegister+apps/docs/source.config.ts，id 从编译产物读出），⛔ 不是从库文档推断：properties·properties-1·properties-2·allowed-values·allowed-values-1· …ui/view.mdx（sha256 比对、逐字节相同的副本）：215 个标题 / 215 个不同 id / 0 重复；45 个### Properties铸出properties→properties-44id/ TOC url / 搜索索引）逐条一致，只有一个铸造权威（remarkHeading+ 工作区唯一一份github-slugger@2.0.0）⇒ 今天不存在锚点碰撞，没有任何链接会静默指到错的一节。 损伤类别是可寻址性，不是正确性。
我要求的那两条控制，都做到了，而且超出要求
第 2 条（「没人链到这些锚点」这个否定）我当时要求「配阳性对照，一个没有对照的零不算数」。交付的是三重对照：
#mcp-server#retrieving-knowledge#properties-17/#option-1-1check:doc-anchorsduplicate counters⇒ 真有这种链接会被解析而非跳过7296 个跟踪文件里，六个锚点（裸的与带后缀的、大小写敏感与不敏感）全部 0 命中。
references/**的真实入链只有 2 条，都指向唯一的 schema 名 H2。⭐ 这是本轮见到的最干净的一次零结论论证。
裁定与理由
accept + 在渲染器里写明，依据是测量而非口味：
properties-17意思是「文档序第 18 个 Properties」⇒ 在同页更早处插入一个 schema section 会静默重编号其下所有锚点。⇒ 换句话说，section-grammar 锚点即便去重也本就不稳定，qualify 才能买到稳定寻址，而那正是最贵的那条。⇒ 落地内容：在渲染器处写明「section-grammar 标题按设计重复，其 id 由 slugger 位置性去重，不是稳定锚点」，让下一个想链过去的人当场知道。
⛔ 本席的边界与退路
「accept + 写明」是不改变任何已发布行为的那一条 —— 是空动作加一条说明，因此在分诊重新定级的权限内。
⛔ 另注：本卡不是 #12590 的续集（那张修的是限定符失效；本卡问的是这一类本来该不该有限定符），此判断在 8-28 的定级里已作出，读数未改变它。
Generated by Claude Code